MCP Server

python-checkup includes an MCP (Model Context Protocol) server that exposes health analysis to AI coding agents over stdio.

Quick Setup

uvx --from 'python-checkup[mcp]' python-checkup mcp install

This auto-detects your installed editors (Claude Code, Cursor, VS Code) and writes the appropriate MCP configuration.

Manual Setup

Claude Code

Add to ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "python-checkup": {
      "command": "python-checkup",
      "args": ["--mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "python-checkup": {
      "command": "python-checkup",
      "args": ["--mcp"]
    }
  }
}

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "python-checkup": {
      "command": "python-checkup",
      "args": ["--mcp"]
    }
  }
}

Available Tools

The MCP server exposes 5 tools:

python_checkup_diagnose

Full health scan. Returns the overall score, category breakdown, top issues, and suggestions.

Parameters:

• path (string, required) -- Path to the project directory

python_checkup_lint

Run only Ruff linting.

Parameters:

• path (string, required) -- Path to analyze

python_checkup_typecheck

Run only mypy type checking.

Parameters:

• path (string, required) -- Path to analyze

python_checkup_security

Run only Bandit security scanning.

Parameters:

• path (string, required) -- Path to analyze

python_checkup_explain_rule

Look up a rule by ID and get an explanation with good/bad code examples.

Parameters:

• rule_id (string, required) -- Rule ID (e.g., S101, B301, C901, mypy-return-value)

Supports alias resolution: B301 maps to S301, mypy-xxx resolves [xxx] bracket syntax.

Starting the Server Directly

uvx --from 'python-checkup[mcp]' python-checkup --mcp

This starts the MCP server on stdio transport. It's designed to be launched by editors, not run manually.

Warning

Never print() to stdout in MCP server mode. All logging goes to stderr.