MCP Tools Py

A Model Context Protocol (MCP) server providing code quality checking operations with easy client configuration. This server offers an API for performing code quality checks within a specified project directory, following the MCP protocol design.

Overview

This MCP server enables AI assistants like Claude (via Claude Desktop), VSCode with GitHub Copilot, or other MCP-compatible clients to run code quality checks, formatting and refactoring on Python projects. See Available Tools for the full list.

Scope: This server covers Python projects only. Support for other languages can be provided through separate, dedicated MCP servers with similar functionality.

Why a dedicated MCP server instead of bash access?

A general-purpose bash MCP tool allows more flexibility, but at the expense of less control. This server takes a more focused approach:

• Security: Only a defined set of tools can be executed — see Available Tools. All operations are scoped to the specified project_dir.
• Context management: Results are formatted and size-limited to reduce context load on the AI assistant. Output is structured as actionable prompts rather than raw tool output.
• Transparency: The server is open source, and detailed structured logging records every tool call with parameters, timing, and results.

Features

All tools are listed under Available Tools. The sections below document the parameters of the most-used ones.

Pylint Parameters

The pylint tools expose the following parameters for customization:

Pylint Configuration

Pylint reads your project's pyproject.toml automatically. Control which issues are reported by configuring [tool.pylint.messages_control] in your pyproject.toml. See docs/pyproject-configuration.md for examples and migration guidance.

Target Directory Auto-Detection

When target_directories is not specified, the tools that accept it (pylint, mypy, ruff check, ruff fix, bandit, vulture, and run_format_code) auto-detect directories from pyproject.toml:

• Source dirs from [tool.setuptools.packages.find] where (fallback: ["src"])
• Test dirs from [tool.pytest.ini_options] testpaths (fallback: ["tests"])

run_deptry_check auto-detects source directories only, excluding test paths.

Only directories that exist on disk are included. You can override auto-detection by passing an explicit list:

• ["src"] - Analyze only source code directory
• ["src", "tests"] - Analyze both source and test directories
• ["mypackage", "tests"] - For projects with different package structures
• ["."] - Analyze entire project directory (may be slow for large projects)

Pytest Parameters

run_pytest_check exposes the following parameters for customization:

Note: Parallel test execution is enabled by default using pytest-xdist (-n auto).

Coverage: coverage=True needs pytest-cov installed in the project's environment. The digest gives the total, the modules with the most missing statements and their per-function line ranges, the modules with nothing covered, and the test selection the numbers come from. The project's fail_under is reported but not applied, so pass/fail reflects the tests only. To exclude code, use coverage's own [tool.coverage.run] omit or # pragma: no cover.

Mypy Parameters

The mypy tools expose the following parameters for customization:

Mypy Configuration

Mypy reads your project's pyproject.toml automatically, and [tool.mypy] is the single source of truth for the flag set — the tool adds only output-formatting flags, unless you pass follow_imports, cache_dir or disable_error_codes. A project with no [tool.mypy] section of its own has no floor: with no config in scope it runs at mypy's defaults and reports "passed" having checked very little; with a parent directory's config (mypy 1.15 and later) or a user-level ~/.config/mypy/config or ~/.mypy.ini in scope it runs at those settings and can report errors the project never asked for. See docs/pyproject-configuration.md for migration guidance and the effect on mypy's cache.

Command Line Interface (CLI)

Basic Usage

mcp-tools-py --project-dir /path/to/project [options]

Required Parameters

Optional Parameters

Python Configuration

Test Configuration

Logging Configuration

Tool Configuration

Notes

• When the deprecated --venv-path is specified, it takes precedence over --python-executable. Resolving the interpreter is now its only effect
• The --console-only flag is useful during development to avoid creating log files
• Log files are created in JSON format for structured analysis
• Temporary files are automatically cleaned up unless --keep-temp-files is specified

Environment Configuration

Two environments are in play, and only one of them is configurable:

• project env — named by --python-executable. It holds your project's dependencies, and pytest, pylint, mypy and deptry, which have to import or inspect those dependencies to do their work. Library and symbol resolution (get_library_source, list_symbols, find_references) follows the same interpreter, so pointing the flag at the wrong venv makes those tools resolve against the wrong packages.
• tool env — where mcp_tools_py itself is installed. It supplies black, isort, ruff, bandit, vulture, tach and lint-imports, which are mcp-tools-py's own dependencies. It is not configurable.

Those seven therefore run at the tool env's versions, which may differ from what your project pins, so a project that cares about parity with its CI should keep compatible ranges in both places. lint-imports still checks your working tree: it runs from the tool env, but finds the project's root package, read from the import-linter config and located through the project interpreter. A custom contract_types entry inside that root package still resolves through the same bridge; one that lives in a separate distribution installed only in the project env does not, since only the root package's directory is handed over.

The first example below builds that path by interpolating an environment variable, so an unset or stale variable leaves --python-executable pointing nowhere. The server then fails at startup with a FileNotFoundError naming the flag, rather than starting up and reporting the project's tools as missing. A bare interpreter name such as python3 is looked up on PATH instead.

Correct Configuration

Point to the project's venv, with pytest, pylint and mypy installed in it, here on Windows:

{
    "mcpServers": {
        "mcp-tools-py": {
            "command": "mcp-tools-py",
            "args": [
                "--project-dir", "/path/to/your/project",
                "--python-executable", "${VIRTUAL_ENV}\\Scripts\\python.exe"
            ]
        }
    }
}

On macOS and Linux the interpreter sits in bin instead:

                "--python-executable", "${VIRTUAL_ENV}/bin/python"

Incorrect Configuration

Do not point to an interpreter that is not the project's:

{
    "mcpServers": {
        "mcp-tools-py": {
            "command": "mcp-tools-py",
            "args": [
                "--project-dir", "/path/to/your/project",
                "--python-executable", "/usr/bin/python3"
            ]
        }
    }
}

A system interpreter, or any venv that is not the project's, reports pytest, pylint and mypy as missing and resolves library and symbol lookups against the wrong packages. Your project's own .venv fails the same way if those three are not installed in it — install them there rather than pointing the flag elsewhere.

Troubleshooting

• "Python interpreter not found" at startup: --python-executable points at a path that doesn't exist — usually because the environment variable it interpolates is unset. The message names the flag that supplied the path.
• "No module named pytest" (or pylint/mypy): Your --python-executable points to an environment that doesn't have the required tools installed. Point it at the project's environment and install them there.
• "ruff is not available" (or black/isort/bandit/vulture/tach/lint-imports): these console scripts come from the tool env, not from --python-executable, so the flag is not the problem. They are dependencies of mcp-tools-py, and the message names the tool env directory searched: reinstall mcp-tools-py with its dependencies and restart the server.
• After installing missing tools: pytest, pylint and mypy are answered by a probe of the configured interpreter that runs once and is cached for the process lifetime, so restart the MCP server after installing one of those three.

Installation

See INSTALL.md for detailed installation instructions.

Quick install:

# Install from GitHub (recommended)
pip install git+https://github.com/MarcusJellinghaus/mcp-tools-py.git

# Verify installation
mcp-tools-py --help

Development install:

# Clone and install for development
git clone https://github.com/MarcusJellinghaus/mcp-tools-py.git
cd mcp-tools-py
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e ".[dev]"
mcp-tools-py --help

MCP Client Configuration

This server can be configured with mcp-config, a separate Python tool you install yourself — it is not a dependency of this package. It provides:

• Interactive setup: Works with Claude Desktop and VSCode
• Configuration management: Add, remove, and view server configurations
• Server repository: Access to curated MCP server collection

Prerequisites: Install Python, then install mcp-config separately.

Note: While other MCP clients like Windsurf and Cursor support MCP servers, they may require manual configuration.

Using as a Dependency

In requirements.txt

Add this line to your requirements.txt:

mcp-tools-py @ git+https://github.com/MarcusJellinghaus/mcp-tools-py.git

In pyproject.toml

Add to your project dependencies:

[project]
dependencies = [
    "mcp-tools-py @ git+https://github.com/MarcusJellinghaus/mcp-tools-py.git",
    # ... other dependencies
]

# Or as an optional dependency
[project.optional-dependencies]
dev = [
    "mcp-tools-py @ git+https://github.com/MarcusJellinghaus/mcp-tools-py.git",
]

Installation Commands

After adding to requirements.txt or pyproject.toml:

# Install from requirements.txt
pip install -r requirements.txt

# Install from pyproject.toml
pip install .
# Or with optional dependencies
pip install ".[dev]"

Running the Server

Using the CLI Command (Recommended)

After installation, you can run the server using the mcp-tools-py command:

mcp-tools-py --project-dir /path/to/project [options]

Using Python Module (Alternative)

You can also run the server as a Python module:

python -m mcp_tools_py --project-dir /path/to/project [options]

# Or for development (from source directory)
python -m src.main --project-dir /path/to/project [options]

For detailed information about all available command-line options, see the CLI section.

Project Structure Support

The server automatically detects and analyzes Python code in standard project structures:

Default Analysis:

• src/ directory (if present) - Main source code
• tests/ directory (if present) - Test files

Custom Project Structures: Use the target_directories parameter to specify different directories:

# For a package-based structure
target_directories = ["mypackage", "tests"]

# For a simple project with code in root
target_directories = ["."]

# For complex multi-module projects
target_directories = ["module1", "module2", "shared", "tests"]

Structured Logging

The server provides comprehensive logging capabilities:

• Standard human-readable logs to console for development/debugging
• Structured JSON logs to file for analysis and monitoring
• Function call tracking with parameters, timing, and results
• Automatic error context capture with full stack traces
• Configurable log levels (DEBUG, INFO, WARNING, ERROR, CRITICAL)
• Default timestamped log files in project_dir/logs/mcp_tools_py_{timestamp}.log

Example structured log entries:

{
  "timestamp": "2025-08-05 14:30:15",
  "level": "info",
  "event": "Starting pylint check",
  "project_dir": "/path/to/project",
  "target_directories": ["src", "tests"],
  "max_issues": 1
}

Use --console-only to disable file logging for simple development scenarios.

Quick MCP Client Setup

Automated Setup (Recommended)

1. First install the server:

   pip install git+https://github.com/MarcusJellinghaus/mcp-tools-py.git
   

   Copy

2. Configure with mcp-config (install it separately — it is not pulled in by this package):

   mcp-config
   

   Copy

   Then select "Add New" and search for this server.

This will prompt you for your project directory and automatically configure your MCP client.

Note: mcp-config's server registry does not yet carry an entry for mcp-tools-py, so use the Manual Setup below if it cannot find this server.

Manual Setup

If you prefer manual configuration, edit your MCP configuration file:

Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
    "mcpServers": {
        "mcp-tools-py": {
            "command": "mcp-tools-py",
            "args": ["--project-dir", "/path/to/your/project"]
        }
    }
}

For development mode:

{
    "mcpServers": {
        "mcp-tools-py": {
            "command": "python",
            "args": [
                "-m",
                "src.main",
                "--project-dir",
                "/path/to/your/project"
            ],
            "env": {
                "PYTHONPATH": "/path/to/mcp-tools-py"
            }
        }
    }
}

VSCode (.vscode/mcp.json):

{
    "servers": {
        "mcp-tools-py": {
            "command": "mcp-tools-py",
            "args": ["--project-dir", "."]
        }
    }
}

VSCode development mode:

{
    "servers": {
        "mcp-tools-py": {
            "command": "python",
            "args": ["-m", "src.main", "--project-dir", "."],
            "env": {
                "PYTHONPATH": "/path/to/mcp-tools-py"
            }
        }
    }
}

Testing with MCP Inspector

npx @modelcontextprotocol/inspector mcp-tools-py --project-dir /path/to/project

Available Tools

The server exposes 19 MCP tools.

Parameters for pylint, pytest and mypy are documented under Features.

Development

Setting up the development environment

# Clone the repository
git clone https://github.com/MarcusJellinghaus/mcp-tools-py.git
cd mcp-tools-py

# Create and activate a virtual environment
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On Unix/MacOS:
source .venv/bin/activate

# Install dependencies
pip install -e .

# Install development dependencies
pip install -e ".[dev]"

Running with MCP Dev Tools

# Set the PYTHONPATH and run the server module using mcp dev
set PYTHONPATH=. && mcp dev src/server.py

License

This project is licensed under the MIT License - see the LICENSE file for details.

The MIT License is a permissive license that allows reuse with minimal restrictions. It permits use, copying, modification, and distribution with proper attribution.

Links

• MCP Python SDK
• MCP Filesystem Tools