jons-mcp-pyright

A FastMCP stdio server that exposes Pyright language intelligence through MCP. It starts Pyright as a subprocess, keeps LSP document state fresh with disk contents, and provides root-bound tools for navigating and understanding Python projects.

Installation

Run directly from PyPI:

uvx jons-mcp-pyright /path/to/python/project

Install as a CLI tool:

uv tool install jons-mcp-pyright
jons-mcp-pyright /path/to/python/project

Run an unreleased version directly from GitHub:

uvx --from git+https://github.com/jonmmease/jons-pyright-mcp.git jons-mcp-pyright /path/to/python/project

Run from a local checkout:

git clone https://github.com/jonmmease/jons-pyright-mcp.git
cd jons-pyright-mcp
uv sync --group dev
uv run jons-mcp-pyright /path/to/python/project

The command is jons-mcp-pyright. The final optional argument is the target project root. If omitted, the server uses its current working directory.

MCP Client Setup

Claude Code

From the Python project you want Pyright to analyze:

claude mcp add --scope project jons-mcp-pyright -- \
  uvx jons-mcp-pyright "$(pwd)"

For a local server checkout:

claude mcp add --scope project jons-mcp-pyright -- \
  uv run --project /path/to/jons-pyright-mcp \
  jons-mcp-pyright "$(pwd)"

Codex CLI

codex mcp add jons-mcp-pyright -- \
  uvx jons-mcp-pyright /path/to/python/project

.mcp.json

{
  "mcpServers": {
    "jons-mcp-pyright": {
      "command": "uvx",
      "args": [
        "jons-mcp-pyright",
        "/absolute/path/to/python/project"
      ]
    }
  }
}

Codex TOML

[mcp_servers.jons-mcp-pyright]
command = "uvx"
args = [
  "jons-mcp-pyright",
  "/absolute/path/to/python/project",
]

Project Root Semantics

The configured project root is the filesystem boundary for all MCP tool file inputs.

• Relative paths resolve from the configured project root, not the MCP process cwd.
• Absolute paths and file:// URIs must resolve inside the configured root.
• .. escapes, symlink escapes, missing files, and directories are rejected before Pyright or the filesystem is touched.
• LSP responses may include external locations, but the server does not open or read external files for enrichment.

Pyright reads pyrightconfig.json or [tool.pyright] from the selected root and discovered nested project roots. If a discovered project is inside a uv workspace, the server uses the nearest enclosing [tool.uv.workspace] root as the Pyright environment so shared workspace dependencies and .venv settings resolve correctly. Virtual environments are detected from common names such as .venv, venv, .env, and Pixi environments under .pixi/envs/<name>.

For uv workspaces, the public diagnostics tool also applies diagnostics-only output filtering from in-root member pyrightconfig.json or [tool.pyright] files. This honors explicit top-level report* overrides such as reportMissingImports = "none" for files under that member without splitting the workspace into separate Pyright processes. The filter affects returned MCP diagnostics only; Pyright analysis, readiness, references, and rename previews continue to use the shared workspace process.

Prerequisites

• Python 3.10 or newer.
• uv for the documented install commands.
• A Python target project. For best results, include pyrightconfig.json or pyproject.toml.
• Target-project dependencies should be installed in the environment Pyright should analyze. The server can also be pointed at a specific Pyright command with PYRIGHT_PATH.

Tools

Navigation and discovery:

• document_symbols
• definition
• type_definition
• references

Understanding code:

• symbol_info
• type_info

Code intelligence and refactoring:

• diagnostics
• preview_rename

Server management:

• list_environments
• restart_server

All public line and character inputs and returned ranges are one-based. preview_rename is preview-only: it returns sorted text edits and never writes files. type_info works best when called on a value reference such as obj in obj.method(), rather than on a class or variable declaration, when member discovery is desired.

references and preview_rename are scoped to the active Pyright workspace/environment for the input file. preview_rename supplements Pyright's rename edit with reference locations from the same workspace so imported callers are included in the preview. By default, preview_rename also prewarms unopened Python files in the active environment before collecting references; tune this with prewarm, prewarm_limit, and prewarm_timeout_seconds. If prewarm is disabled or partial, the result includes warnings. In monorepos, callers that need results beyond the active workspace should iterate environments or combine the preview with external search before applying edits.

Paginated tools return items, totalItems, offset, limit, hasMore, and nextOffset. Navigation tools return items and totalItems. Errors use a structured error.code, error.message, and error.retryable shape.

Development

uv sync --group dev
uv run pytest
uv run pytest --cov=src/jons_mcp_pyright --cov-report=term-missing
uv run ruff check .
uv run mypy src
uv build --wheel --out-dir /tmp/jons-mcp-pyright-wheel

Inspect a built wheel:

uv run python -m zipfile -l /tmp/jons-mcp-pyright-wheel/jons_mcp_pyright-*.whl

The wheel should contain top-level jons_mcp_pyright, not a packaged top-level src module, and should not include build artifacts or node_modules.