MCP Tools Py

What is MCP Tools Py about?

MCP Tools Py offers a Model Context Protocol (MCP) server that runs static analysis, testing, and type‑checking tools on a Python codebase and formats the results as smart prompts for large language models. It limits execution to the specified project directory, logs operations in structured JSON, and presents output in a concise, AI‑ready form.

How to use MCP Tools Py?

1. Install the server (recommended):

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

2. Run the server via the CLI, pointing it at the project you want to check:

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

   Common options include --venv-path or --python-executable to select the environment where pylint, pytest, and mypy are installed, --log-level to control verbosity, and --log-file to write structured logs.
3. Configure your MCP client (Claude Desktop, VS Code, etc.) to call the mcp-tools-py command with the same arguments. The client can then request specific tools such as run_pylint_check, run_pytest_check, or run_mypy_check.

Key Features

• Run Pylint Check – Executes pylint, reads pyproject.toml for configuration, and returns LLM‑ready prompts.
• Run Pytest Check – Runs pytest (parallel execution enabled by default) with customizable markers, verbosity, and environment variables.
• Run Mypy Check – Performs strict type checking with options to disable error codes and control import handling.
• Parameter Customization – Extra CLI arguments, target directory selection, and environment variable injection.
• Auto‑Detection of Target Directories – Sources and test folders are inferred from pyproject.toml when not supplied.
• Security‑Focused Execution – Only the defined tools can run, and all actions are scoped to project_dir.
• Structured JSON Logging – Detailed logs include timestamps, parameters, execution time, and results; optional console‑only mode for quick debugging.
• LLM‑Friendly Output – Results are condensed into actionable prompts rather than raw tool dumps, reducing token usage for downstream assistants.

Use Cases

• AI‑Assisted Code Review – Claude, Cursor, or other assistants call the server to get concise issue reports and suggested fixes.
• Continuous Integration – Integrate the server into CI pipelines to produce LLM‑ready reports that can be automatically posted to PR comments.
• Developer Productivity – Run a single command locally to obtain both linting, testing, and type‑checking feedback formatted for quick copy‑paste into an LLM chat.
• Educational Tools – Teaching environments can expose students to automated feedback that an LLM can explain in natural language.

FAQ

Q: Which Python interpreter should I point to? A: Use --venv-path to specify the virtual environment that contains pytest, pylint, and mypy. If omitted, the server falls back to the interpreter used for installing the package.

Q: What if the required tools are not installed? A: The server will raise a “No module named …” error. Install the missing tools in the selected environment and restart the server.

Q: Can I analyze a project with a custom folder layout? A: Yes. Provide target_directories (for pylint/mypy) or test-folder (for pytest) to override the auto‑detected defaults.

Q: How are logs stored? A: By default logs are written to project_dir/logs/mcp_tools_py_<timestamp>.log in JSON format. Use --console-only to suppress file logging.

Q: Is parallel test execution safe? A: Parallelism is enabled via pytest‑xdist (-n auto). Ensure your tests are written to be thread‑/process‑safe.

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 on Python projects. The tools provided are:

• Run pylint checks to identify code quality issues
• Execute pytest to identify failing tests
• Run mypy for type checking

Scope: This server covers Python projects only. Further Python-specific extensions are planned, including architecture and layering checks (vulture, tach, import-linter) and refactoring tools. 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 (pylint, pytest, mypy) can be executed. 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

• run_pylint_check: Run pylint on the project code and generate smart prompts for LLMs
• run_pytest_check: Run pytest on the project code and generate smart prompts for LLMs
• run_mypy_check: Run mypy type checking on the project code

Pylint Parameters

The pylint tools expose the following parameters for customization:

Parameter	Type	Default	Description
extra_args	list	None	Optional list of additional pylint CLI arguments (e.g. ["--disable=W0611"])
target_directories	list	None (auto-detected)	Directories to analyze relative to project_dir. Auto-detected from pyproject.toml when omitted

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, all checker tools (pylint, mypy, vulture) 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"])

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:

Parameter	Type	Default	Description
markers	list	None	Optional list of pytest markers to filter tests
verbosity	integer	2	Pytest verbosity level (0-3)
extra_args	list	None	Optional list of additional pytest arguments
env_vars	dictionary	None	Optional environment variables for the subprocess

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

Mypy Parameters

The mypy tools expose the following parameters for customization:

Parameter	Type	Default	Description
strict	boolean	True	Use strict mode settings
disable_error_codes	list	None	List of mypy error codes to ignore
target_directories	list	None (auto-detected)	Directories to check relative to project_dir. Auto-detected from pyproject.toml when omitted
follow_imports	string	'normal'	How to handle imports during type checking

Command Line Interface (CLI)

Basic Usage

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

Required Parameters

Parameter	Type	Description
--project-dir	string	Required. Base directory for code checking operations

Optional Parameters

Python Configuration

Parameter	Type	Default	Description
--python-executable	string	sys.executable	Path to Python interpreter for running pytest, pylint, and mypy. Should point to the environment where these tools are installed (the tool's own venv), not the project's runtime venv
--venv-path	string	None	Path to the virtual environment where pytest, pylint, and mypy are installed. When specified, this venv's Python will be used instead of --python-executable. This should be the tool's own venv, not the project's runtime venv

Test Configuration

Parameter	Type	Default	Description
--test-folder	string	"tests"	Path to the test folder (relative to project-dir)
--keep-temp-files	flag	False	Keep temporary files after test execution. Useful for debugging when tests fail

Logging Configuration

Parameter	Type	Default	Description
--log-level	string	"INFO"	Set logging level. Choices: DEBUG, INFO, WARNING, ERROR, CRITICAL
--log-file	string	None	Path for structured JSON logs. If not specified, logs only to console
--console-only	flag	False	Log only to console, ignore --log-file parameter

Notes

• When --venv-path is specified, it takes precedence over --python-executable
• 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

The --python-executable and --venv-path options must point to the environment where pytest, pylint, and mypy are installed — this is typically the tool's own virtual environment, not your project's runtime venv.

Correct Configuration

Point to the venv where mcp-tools-py and its tools are installed:

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

Incorrect Configuration

Do not point to your project's runtime venv if it doesn't have pytest/pylint/mypy installed:

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

This will fail if your project's .venv doesn't have the required tools installed.

Troubleshooting

• "No module named pytest" (or pylint/mypy): Your --python-executable or --venv-path points to an environment that doesn't have the required tools installed. Update the configuration to point to the correct environment.
• After installing missing tools, restart the MCP server for changes to take effect. Tool availability is checked at startup and cached for the session.

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 easily configured using the mcp-config Python tool. The mcp-config tool 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 and the mcp-config tool.

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",
  "disable_codes": ["C0114", "C0116"],
  "target_directories": ["src", "tests"]
}

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
   

2. Configure with mcp-config:

   mcp-config
   

   Then select "Add New" and search for this server, or run directly:

   mcp-config mcp-tools-py
   

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

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 the following MCP tools:

Run Pylint Check

• Runs pylint on the project code and generates smart prompts for LLMs
• Returns: A string containing either pylint results or a prompt for an LLM to interpret
• Helps identify code quality issues, style problems, and potential bugs
• Customizable with parameters for disabling specific pylint codes and targeting specific directories
• Supports flexible project structures through target_directories parameter

Run Pytest Check

• Runs pytest on the project code and generates smart prompts for LLMs
• Returns: A string containing either pytest results or a prompt for an LLM to interpret
• Identifies failing tests and provides detailed information about test failures
• Customizable with parameters for test selection, environment, and verbosity

Run Mypy Check

• Runs mypy type checking on the project code
• Returns: A string containing mypy results or a prompt for an LLM to interpret
• Identifies type errors and provides suggestions for better type safety
• Customizable with parameters for strict mode, error code filtering, and target directories

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