Ruff-MCP

Ruff MCP Server

An MCP server that gives AI assistants Ruff, the Python linter and formatter, as callable tools.

Tools

Tool	What it runs
ruff_check	ruff check on a file or directory
ruff_format	ruff format on a file or directory
ruff_fix	ruff check --fix on a file or directory

ruff_check

Argument	Type	Default	Description
path	string	required	File or directory to check
fix	boolean	false	Apply the fixes instead of only reporting them
output_format	string	concise	One of concise, full, json, json-lines, junit, sarif

ruff_format

Argument	Type	Default	Description
path	string	required	File or directory to format
check	boolean	false	Report whether formatting is needed, change nothing
diff	boolean	false	Show the diff instead of writing the changes

ruff_fix

Argument	Type	Default	Description
path	string	required	File or directory to fix
unsafe	boolean	false	Also apply the fixes Ruff marks as unsafe

The server also exposes a ruff://docs resource listing the available tools.

Requirements

• Python 3.10 or newer
• Ruff, either on your PATH or pointed at by the RUFF_EXE environment variable

Install Ruff with whichever of these suits you:

pip install ruff
winget install astral.Ruff                   # Windows
brew install ruff                            # macOS
curl -LsSf https://astral.sh/ruff/install.sh | sh   # Linux

Install

git clone https://github.com/hussainbiedouh/Ruff-MCP.git
cd Ruff-MCP

python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # macOS and Linux

pip install -e .

Add it to your client

The server speaks stdio, which means the client starts it and stops it with the session. Ready-made snippets are in mcp-configs/, and each client expects a different key:

Client	Config file	Key
OpenCode	~/.config/opencode/opencode.jsonc	mcp.servers
Claude Desktop	claude_desktop_config.json	mcpServers
Cursor	~/.cursor/mcp.json	mcpServers
VS Code	.vscode/mcp.json	servers

For OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "ruff-mcp": {
        "type": "local",
        "command": [
          "C:\\path\\to\\Ruff-MCP\\.venv\\Scripts\\python.exe",
          "-m",
          "ruff_mcp"
        ],
        "environment": {
          "PYTHONIOENCODING": "utf-8"
        }
      }
    }
  }
}

Point the command at the full path of the interpreter. The PATH a client inherits is not always the PATH in your shell, and python can resolve to a different install than the one you tested with.

The same file will not work across clients, because the key differs. mcp-client-config has the full table and what each failure mode looks like.

Choosing which ruff to run

The server looks for the executable in this order:

1. the RUFF_EXE environment variable
2. ruff or ruff.exe on PATH
3. ~/.config/opencode/tools/ruff.exe

If none of them turn up an executable, the tool call comes back with an error telling you to install Ruff.

Development

There is no test suite yet. The check that matters is the linter:

pip install ruff
ruff check .

License

MIT