python-mcp
Provides tools to run Ruff linting and format checking on Python projects.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@python-mcp Run ruff check on the current project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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_onlychecks just the files touched in gitruff_format - Verify formatting without modifying files
ty_check - Type-check with concise output and an optional
error/warningseverity filtervulture_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 lintingruff_format(paths?, changed_only?)- Runruff format --checkty_check(paths?, level?, changed_only?)- Runty check --output-format concise, filtering byall/error/warningvulture_check(paths?, changed_only?)- Run vulture dead-code analysisbandit_check(paths?, changed_only?)- Run Bandit security analysisdeptry_check(paths?, changed_only?)- Run deptry dependency analysispytest_collect(paths?, changed_only?)- Collect tests without running themcodespell_check(paths?, changed_only?)- Run codespell spelling analysispydoclint_check(paths?, changed_only?)- Run pydoclint docstring analysis
Output Processing
Command | Input format | Output |
| JSON | Compact grouped output; large runs get rule/file rollups |
| Concise text | One line per unformatted file |
| GitLab JSON | Compact grouped output; severity filter applied |
| Concise text | Compact grouped dead-code findings |
| JSON | Compact grouped security findings |
| ANSI-free text | Compact grouped dependency findings |
| Concise text | Collected test IDs or collection errors |
| Concise text | Compact spelling findings with suggestions |
| Concise text | Compact docstring-signature violations |
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-mcpOr from a checkout:
uv run python-mcpConfigure 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, defaultINFOPYTHON_MCP_PROJECT_DIR- Project directory to check, default: server working directoryPYTHON_MCP_COMMAND_PREFIX- Prefix for native ruff/ty/vulture invocations, defaultuv run; set to empty to use binaries fromPATHPYTHON_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 pytestAvailable Tools
9 toolsbandit_checkBRead-onlyIdempotent
Scan Python code for common security problems with Bandit.
Inputs: paths, changed_only. Returns: Result of a code-quality check run. Attributes: output: Token-efficient output…
codespell_checkARead-onlyIdempotent
Find likely spelling mistakes in project text and source files.
Inputs: paths, changed_only. Returns: Result of a code-quality check run. Attributes: output: Token-efficient output…
deptry_checkBRead-onlyIdempotent
Find missing, unused, obsolete, and misplaced dependencies.
Inputs: paths, changed_only. Returns: Result of a code-quality check run. Attributes: output: Token-efficient output…
pydoclint_checkCRead-onlyIdempotent
Check docstrings against function signatures with pydoclint.
Inputs: paths, changed_only. Returns: Result of a code-quality check run. Attributes: output: Token-efficient output…
pytest_collectARead-onlyIdempotent
Collect pytest tests without executing them.
Inputs: paths, changed_only. Returns: Result of a code-quality check run. Attributes: output: Token-efficient output…
ruff_checkARead-onlyIdempotent
Run ruff linting with token-efficient output.
Inputs: paths, changed_only. Returns: Result of a code-quality check run. Attributes: output: Token-efficient output…
ruff_formatCRead-onlyIdempotent
Check Ruff formatting without modifying files.
Inputs: paths, changed_only. Returns: Result of a code-quality check run. Attributes: output: Token-efficient output…
ty_checkBRead-onlyIdempotent
Run ty type checking with an optional severity filter.
Inputs: level, paths, changed_only. Returns: Result of a code-quality check run. Attributes: output: Token-efficient output…
vulture_checkBRead-onlyIdempotent
Find unused Python code with Vulture's dead-code analysis.
Inputs: paths, changed_only. Returns: Result of a code-quality check run. Attributes: output: Token-efficient output…
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool maps to a distinct well-known Python quality concern: linting, formatting, type checking, dead code, security, dependencies, test discovery, spelling, and docstrings. There is no meaningful overlap between tools despite several sharing a 'check' suffix.
All tool names follow a consistent lowercase snake_case pattern of <tool>_<action>, with 'check' used for most tools and 'format'/'collect' used only where semantically appropriate. The convention is predictable and easy to infer.
Nine tools is a well-scoped size for a Python code-quality server. Each tool covers a major independent concern without unnecessary redundancy or bloat.
The tool surface covers the core Python quality-checking lifecycle: linting, formatting validation, type checking, dead-code analysis, security scanning, dependency validation, test discovery, spelling, and docstring consistency. No critical gaps are apparent for the evident check-oriented purpose.
Maintenance
Related MCP Connectors
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Free, no-key MCP server: token estimates, JSON Schema conversion, MCP configs, tool search.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that exposes Pyright language server functionality for Python, providing tools for type checking, code completions, and finding definitions. It enables AI models to perform static analysis and code formatting through the Model Context Protocol.729 PyPIMIT
- AlicenseBqualityBmaintenanceAn MCP server that performs comprehensive Python code analysis using Ruff, ty, and Vulture for linting, type checking, and dead code detection.8144 PyPI11MIT
- AlicenseNot gradedqualityDmaintenanceCode linting and style checking tools for AI agents, exposed as an MCP server. Supports style checks, naming conventions, complexity analysis, dead code detection, and import analysis.40 npmMIT
- AlicenseBqualityDmaintenanceAn MCP server that integrates Ruff linting, formatting, and code analysis tools with advanced logging and configuration options for AI coding assistants.41MIT