python-mcp

A Model Context Protocol (MCP) server for Python code-quality checks with token-efficient output.

Overview

python-mcp gives LLMs direct access to linting, formatting, type checking, security, dependency, test-collection, dead-code, and spelling checks. Tool output is parsed structurally and reduced to compact diagnostics before it reaches the model.

Related MCP server: mcp-server-analyzer

Features

• ruff_check - Lint files, glob patterns, or everything; changed_only checks just the files touched in git

• ruff_format - Verify formatting without modifying files

• ty_check - Type-check with concise output and an optional error/warning severity filter

• vulture_check - Find unused code and other dead-code candidates

• bandit_check - Find common Python security problems

• deptry_check - Find missing, unused, obsolete, and misplaced dependencies

• pytest_collect - Verify that tests can be collected without executing them

• codespell_check - Find likely spelling mistakes in source and documentation

• pydoclint_check - Check docstrings against function signatures

• Structured parsing - ruff JSON and ty GitLab code-quality output avoid fragile parsing of human-readable text

• Adaptive aggregation - large result sets include rule/file rollups before flat diagnostics, reducing repeated context

• changed_only - Check only staged, unstaged, and untracked Python files (*.py, *.pyi)

How It Works

python-mcp implements the Model Context Protocol to expose nine read-only tools. All tools return a CheckResult with token-efficient output text and the underlying exit_code.

Tools

• ruff_check(paths?, changed_only?) - Run ruff linting

• ruff_format(paths?, changed_only?) - Run ruff format --check

• ty_check(paths?, level?, changed_only?) - Run ty check --output-format concise, filtering by all / error / warning

• vulture_check(paths?, changed_only?) - Run vulture dead-code analysis

• bandit_check(paths?, changed_only?) - Run Bandit security analysis

• deptry_check(paths?, changed_only?) - Run deptry dependency analysis

• pytest_collect(paths?, changed_only?) - Collect tests without running them

• codespell_check(paths?, changed_only?) - Run codespell spelling analysis

• pydoclint_check(paths?, changed_only?) - Run pydoclint docstring analysis

Output Processing

Small and medium result sets use the plugin-compatible grouped layout because it has lower overhead. Large result sets switch to an rtk-like layout with Top rules, Top files, and flat diagnostic lines. This addresses rtk's large-result advantage without adding an external runtime dependency.

Usage

To start the server:

uvx python-mcp

Or from a checkout:

uv run python-mcp

Configure an MCP client to launch the server in the project directory to check, e.g. for opencode:

{
  "mcp": {
    "python-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["python-mcp"]
    }
  }
}

The server checks the project in its working directory. To target another directory, set PYTHON_MCP_PROJECT_DIR.

Agent Skill

Install the bundled python-mcp skill in a project when the agent client discovers skills from .agents/skills:

uvx python-mcp skill install python-mcp --target .

The skill directs agents to the server's nine read-only tools: ruff_check, ruff_format, ty_check, vulture_check, bandit_check, deptry_check, pytest_collect, codespell_check, and pydoclint_check. It does not describe uv package or environment management.

Configuration

Environment variables, all optional:

• PYTHON_MCP_LOG_LEVEL - Logging level, default INFO

• PYTHON_MCP_PROJECT_DIR - Project directory to check, default: server working directory

• PYTHON_MCP_COMMAND_PREFIX - Prefix for native ruff/ty/vulture invocations, default uv run; set to empty to use binaries from PATH

• PYTHON_MCP_COMMAND_TIMEOUT - Optional command timeout in seconds

Development

This project is built with FastMCP and uv.

uv sync --extra dev
uv run ruff check
uv run ty check
uv run pytest