Pyright MCP Server

pyright-mcp

An MCP (Model Context Protocol) server that exposes Pyright's Python static type checking capabilities to LLM clients like Claude.

Status: Phase 3 Complete - Production-ready with multi-workspace support, completions, and references. See STATUS.md for details.

Features

Installation

From Source (Recommended for Development)

git clone https://github.com/islee/pyright-mcp-server.git
cd pyright-mcp-server
uv sync
uv run python -m pyright_mcp

From PyPI (When Published)

# Via uv (recommended)
uv add pyright-mcp

# Via pip
pip install pyright-mcp

Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "pyright": {
      "command": "uvx",
      "args": ["pyright-mcp"]
    }
  }
}

For development:

{
  "mcpServers": {
    "pyright": {
      "command": "uv",
      "args": ["--directory", "/path/to/pyright-mcp", "run", "python", "-m", "pyright_mcp"]
    }
  }
}

Usage

Once configured, the MCP tools are available in Claude:

# Check types in a file
check_types("/path/to/file.py")

# Check entire project
check_types("/path/to/project/")

# Get type info at position (Phase 2)
get_hover("/path/to/file.py", line=10, column=5)

# Go to definition (Phase 2)
go_to_definition("/path/to/file.py", line=10, column=5)

# Get completions (Phase 3)
get_completions("/path/to/file.py", line=10, column=5, trigger_character=".")

# Find references (Phase 3)
find_references("/path/to/file.py", line=10, column=5)

# Check health with pool stats and metrics (Phase 3)
health_check()

Phase 3 Features (Production)

Multi-Workspace Support

pyright-mcp now supports efficient multi-workspace development:

• LSP Pool Management: Maintains up to 3 concurrent LSP clients (configurable via PYRIGHT_MCP_LSP_POOL_SIZE)
• LRU Eviction: Automatically manages memory by evicting least-recently-used workspaces
• Per-Workspace Metrics: Tracks operation counts, latencies, and error rates for each workspace

New Tools

• get_completions - Get code completion suggestions at a position with context awareness
• find_references - Find all references to a symbol across the workspace

Enhanced Health Check

The health_check tool now returns detailed pool statistics and per-workspace metrics:

{
  "status": "healthy",
  "lsp_pool": {
    "active_instances": 2,
    "max_instances": 3,
    "cache_hit_rate": 0.667,
    "eviction_count": 1,
    "workspace_switches": 3,
    "workspaces": ["/path/to/workspace1", "/path/to/workspace2"]
  },
  "metrics": {
    "uptime_seconds": 123.45,
    "workspaces": [
      {
        "workspace": "/path/to/workspace1",
        "operations": {
          "hover": {"count": 5, "avg_ms": 25.3, "errors": 0},
          "definition": {"count": 3, "avg_ms": 35.2, "errors": 0},
          "completion": {"count": 2, "avg_ms": 40.1, "errors": 0},
          "references": {"count": 1, "avg_ms": 50.0, "errors": 0}
        }
      }
    ]
  }
}

Use metrics to identify slow workspaces and optimize your Pyright configuration.

Configuration

Control multi-workspace behavior:

# Increase pool size for more concurrent workspaces
export PYRIGHT_MCP_LSP_POOL_SIZE=5

# Increase idle timeout (useful for slower machines)
export PYRIGHT_MCP_LSP_TIMEOUT=600

See docs/METRICS.md for detailed metrics documentation.

Requirements

• Python 3.10+
• uv (recommended) or pip
• Pyright 1.1.350+ (tested with 1.1.350-1.1.408). Run health_check to verify compatibility.
• Node.js (for Pyright, installed automatically via pyright package)

Environment Variables

Development

# Install dependencies
uv sync

# Run the MCP server
uv run python -m pyright_mcp

# Run tests
uv run pytest

# Type check
uv run pyright

# Lint and format
uv run ruff check .
uv run ruff format .

Architecture

┌───────────────────────────────────────────────────────┐
│                      Claude Code                      │
└───────────────────────────┬───────────────────────────┘
                            │ MCP Protocol (stdio)
                            ▼
┌───────────────────────────────────────────────────────┐
│                      pyright-mcp                      │
│  ┌─────────────┐  ┌─────────────┐  ┌───────────────┐  │
│  │ MCP Server  │  │   Tools     │  │ Backend       │  │
│  │ (FastMCP)   │◄─┤ check_types │◄─┤ Pyright CLI   │  │
│  │             │  │ get_hover   │  │ LSP Client    │  │
│  └─────────────┘  └─────────────┘  └───────────────┘  │
└───────────────────────────────────────────────────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
       ┌──────────┐  ┌──────────┐  ┌──────────────┐
       │ Pyright  │  │ Pyright  │  │ Python Files │
       │ CLI      │  │ LSP      │  │ (workspace)  │
       └──────────┘  └──────────┘  └──────────────┘

Documentation

• Product Requirements (PRD)
• Technical Design (TDD)
• Implementation Plan

License

GPL-3.0 - See LICENSE for details.