wemake-python-mcp

Model Context Protocol (MCP) server providing automated code linting, rule explanations, and configuration templates for wemake-python-styleguide (WPS).

Features

• Automatic Venv Resolution: Automatically detects project virtualenvs (.venv, venv, uv) to execute flake8 --select=WPS.

• Structured Violation Output: Returns JSON violation reports with file, line, column, rule code, title, category, and message.

• Offline WPS Rule Database: Bundled offline lookup database covering all 263 WPS rules (WPS000–WPS699).

• Live Scraper & Updater: Scrapes official documentation to keep rule definitions and links up to date.

• FastMCP Protocol Support: Implements tools and resources via standard stdio transport.

Related MCP server: mcp-lint-tools

Prerequisites

• Python 3.10+

• wemake-python-styleguide (installed in target project virtual environment or system environment)

• uv (recommended) or pip

Installation

Using uv (Recommended)

Clone the repository and install dependencies into a local virtualenv:

git clone https://github.com/your-org/wemake-python-mcp.git
cd wemake-python-mcp
uv venv
uv pip install -e .

Using pip

pip install -e .

Usage & MCP Client Configuration

CLI Usage

Run the server over stdio transport:

wemake-python-mcp --transport stdio

Check version:

wemake-python-mcp --version

Claude Desktop / Cursor / MCP Client Configuration

Add the following to your MCP client configuration file (e.g., claude_desktop_config.json):

Using uv (Recommended)

{
  "mcpServers": {
    "wemake-python": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/wemake-python-mcp",
        "run",
        "wemake-python-mcp"
      ]
    }
  }
}

Direct Executable

{
  "mcpServers": {
    "wemake-python": {
      "command": "/absolute/path/to/wemake-python-mcp/.venv/bin/wemake-python-mcp",
      "args": []
    }
  }
}

Tools Reference

Sample Tool Output (lint_file / lint_code)

{
  "success": false,
  "violation_count": 1,
  "violations": [
    {
      "file": "example.py",
      "line": 1,
      "column": 5,
      "code": "WPS432",
      "title": "Forbid magic numbers",
      "category": "Best practices",
      "message": "Found magic number: 42"
    }
  ],
  "summary": "Found 1 wemake-python-styleguide violation across 1 file."
}

Resources Reference

Environment Variables

• WPS_FLAKE8_PATH: Explicit path to flake8 executable. Overrides auto-detection logic.

Development & Testing

Run tests and type checks:

# Run unit tests
uv run pytest

# Type check
uv run mypy src/ tests/

# Ruff linting
uv run ruff check src/ tests/ scripts/

# WPS styleguide compliance check
uv run flake8 src/ tests/ --select=WPS