Python LSP MCP Server

Python MCP server providing code analysis features using Rope and Pyright.

Features

Tool	Description	Backend
hover	Get documentation at position	Rope/Pyright
definition	Go to symbol definition	Rope/Pyright
references	Find all references	Rope/Pyright
completions	Code completion suggestions	Rope/Pyright
symbols	Extract document symbols	Rope/Pyright
rename	Rename refactoring	Rope
move	Move function/class to another module	Rope
change_signature	Change function parameters	Rope
function_signature	Get function signature info	Rope
diagnostics	Type checking errors	Pyright
signature_help	Function signatures	Pyright
update_document	Incremental document updates	Pyright
search	Regex search in files	ripgrep
set_backend	Switch backend at runtime	-
status	Server status info	-

Installation

From PyPI (Recommended)

# Using uvx (no install needed)
uvx python-lsp-mcp@latest

# Using pipx
pipx install python-lsp-mcp

# Using pip
pip install python-lsp-mcp

From Source

cd python
uv sync
uv run python-lsp-mcp

Usage

Run the server

# With uvx (recommended)
uvx python-lsp-mcp@latest

# With pip install
python-lsp-mcp

# From source
uv run python-lsp-mcp

Configure in Claude Code

Add to your .mcp.json or MCP settings:

{
  "mcpServers": {
    "python-lsp-mcp": {
      "command": "uvx",
      "args": ["python-lsp-mcp@latest"]
    }
  }
}

Or if installed from source:

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

MCP Inspector

uvx mcp dev python-lsp-mcp

Configuration

Backend Selection

The server supports two backends for shared tools (hover, definition, references, completions, symbols):

Backend	Strengths	Use Case
rope (default)	Fast, low latency, good refactoring	Quick operations, CI/CD
pyright	Accurate types, cross-file analysis	Type-heavy projects

Runtime Switching

Use the set_backend tool to switch backends at runtime:

# Switch all shared tools to pyright
set_backend(backend="pyright")

# Switch only hover to rope
set_backend(backend="rope", tool="hover")

# Check current configuration
status()

Environment Variables

Configure backends at startup via environment variables (supports both prefixes):

Variable	Description	Default
PYTHON_LSP_MCP_BACKEND	Default backend (rope or pyright)	rope
PYTHON_LSP_MCP_HOVER_BACKEND	Backend for hover	inherited
PYTHON_LSP_MCP_DEFINITION_BACKEND	Backend for definition	inherited
PYTHON_LSP_MCP_REFERENCES_BACKEND	Backend for references	inherited
PYTHON_LSP_MCP_COMPLETIONS_BACKEND	Backend for completions	inherited
PYTHON_LSP_MCP_SYMBOLS_BACKEND	Backend for symbols	inherited
PYTHON_LSP_MCP_NO_CACHE	Disable Rope caching (1 or true)	false

Note: ROPE_MCP_* prefix is also supported for backward compatibility.

Rope Caching

By default, Rope creates a .ropeproject folder in each analyzed project to cache analysis results. This significantly improves performance for medium to large projects.

• Cache location: .ropeproject/ in each project root (project-isolated)
• Cache contents: Module info, object database, refactoring history
• Disable caching: Set PYTHON_LSP_MCP_NO_CACHE=1

You may want to add .ropeproject/ to your .gitignore.

Example:

# Use pyright for all shared tools
PYTHON_LSP_MCP_BACKEND=pyright uvx python-lsp-mcp@latest

# Use pyright for hover only
PYTHON_LSP_MCP_HOVER_BACKEND=pyright uvx python-lsp-mcp@latest

Development

Run tests

uv run pytest tests/ -v

Run benchmarks

uv run pytest tests/test_benchmark.py -v -s

Architecture

┌─────────────────┐     stdio      ┌─────────────────────┐
│  Claude / AI    │ ◄────────────► │     python-lsp-mcp        │
│                 │      MCP       │                     │
└─────────────────┘                └─────────┬───────────┘
                                             │
                           ┌─────────────────┼─────────────────┐
                           │                 │                 │
                           ▼                 ▼                 ▼
                    ┌───────────┐     ┌───────────┐     ┌───────────┐
                    │   Rope    │     │  Pyright  │     │ Pyright   │
                    │  Library  │     │   CLI     │     │   LSP     │
                    └───────────┘     └───────────┘     └───────────┘

Project Structure

python/
├── pyproject.toml
├── src/rope_mcp/
│   ├── server.py           # MCP server entry point
│   ├── rope_client.py      # Rope library wrapper
│   ├── pyright_client.py   # Pyright CLI wrapper
│   ├── config.py           # Backend configuration
│   ├── lsp/                # LSP client for Pyright
│   │   ├── client.py
│   │   └── types.py
│   └── tools/              # Tool implementations
│       ├── hover.py
│       ├── definition.py
│       ├── references.py
│       ├── completions.py
│       ├── symbols.py
│       ├── rename.py
│       └── diagnostics.py
└── tests/
    ├── test_tools.py
    └── test_benchmark.py

Performance

Rope is significantly faster than Pyright LSP for basic operations:

Tool	Rope (ms)	Pyright (ms)	Speedup
hover	0.16	0.79	4.9x
definition	0.12	0.40	3.3x
completions	0.36	1.52	4.2x
symbols	0.24	0.44	1.8x

See docs/BENCHMARKS.md for detailed benchmarks.

License

MIT