py-ast-mcp

An MCP (Model Context Protocol) server for deep structural analysis of Python source code.

It is the Python counterpart to ts-ast-mcp and mirrors its 20-tool surface as closely as Python semantics allow. Everything is built on the standard library ast module — no compilation, no type checker, no project configuration required. jedi is an optional extra used only for cross-file semantic resolution, and every tool degrades gracefully when it is not installed.

Unlike grep, this server understands actual structure: function signatures, class hierarchies, call relationships, cyclomatic complexity and unreferenced code.

Features

• Real AST, not regex — signatures with annotations and defaults, decorators, async flags, positional-only and keyword-only parameters, nested definitions.

• Python-aware classification — dataclasses, enums, Protocol, TypedDict, NamedTuple, ABCs, exceptions and TypeAlias are recognised as distinct kinds.

• Call graphs as Mermaid — file-scoped or package-scoped flowcharts, rooted at a function, with optional external call edges.

• Quality tooling — cyclomatic complexity with ranks, scored to match radon/mccabe, code smells, and Python-specific hazards (mutable default arguments, mutable @dataclass field defaults, bare except, unreachable except clauses, late-binding closures, is against a literal, unawaited coroutines, assert used for validation).

• Dead code across a directory — unreferenced private and module-level symbols, with a confidence split between private and public names.

• Protocol conformance — finds implementations both explicitly (base class, including indirect subclasses) and structurally (method-set match).

• Docstring parsing — Google and NumPy styles are split into summary / params / returns / raises.

• Structural diffing — signature-level, not text-level: what actually changed in the API.

• Model-friendly output — dense, scannable plain text with line numbers everywhere, not raw JSON dumps.

• Never crashes on bad input — syntax errors come back as a readable error with line and column, flagged isError so a client can tell failure from analysis; the server stays up.

• Parse caching — modules are cached by path + mtime + size, so repeated tool calls in one turn are cheap.

Related MCP server: mcp-ast-explorer

Installation

Requires Python 3.10+. Prefer the newest Python you have installed: the server can only parse syntax its own interpreter understands (see Known limitations).

git clone <this-repo> py-ast-mcp
cd py-ast-mcp
pip install -e .

# optional: cross-file semantic resolution
pip install -e ".[semantic]"

# development (pytest + jedi)
pip install -e ".[dev]"

This installs a py-ast-mcp console script that runs the stdio server. python -m py_ast_mcp works too.

Tools

All path arguments accept absolute paths or paths relative to the server's working directory.

Structural

Call analysis

Quality

Docs & multi-file

Configuration

Claude Code

Add a .mcp.json at the root of your project (this file is picked up automatically):

{
  "mcpServers": {
    "py-ast": {
      "command": "py-ast-mcp",
      "args": []
    }
  }
}

If you installed into a virtualenv, point at it explicitly so the server does not depend on your shell's PATH:

{
  "mcpServers": {
    "py-ast": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["-m", "py_ast_mcp"]
    }
  }
}

Or run it straight from a checkout without installing, using uv:

{
  "mcpServers": {
    "py-ast": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/py-ast-mcp", "py-ast-mcp"]
    }
  }
}

You can also register it from the CLI:

claude mcp add py-ast -- py-ast-mcp

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "py-ast": {
      "command": "py-ast-mcp",
      "args": []
    }
  }
}

Because Claude Desktop does not inherit your shell environment, an absolute path is usually safer:

{
  "mcpServers": {
    "py-ast": {
      "command": "/absolute/path/to/venv/bin/py-ast-mcp",
      "args": []
    }
  }
}

Restart Claude Desktop after editing the file.

Straight from GitHub

No checkout, no install - uv fetches and runs it:

{
  "mcpServers": {
    "py-ast": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/gclluch/py-ast-mcp", "py-ast-mcp"]
    }
  }
}

Add --with jedi to the args for cross-file semantic resolution.

Example output

call_graph on a small package:

# call_graph (package)  samplepkg/core.py  [16 functions, 11 edges]

## mermaid
```mermaid
flowchart TD
    n2_core_Engine_store["core.Engine.store L57"]
    n9_util_normalize["util.normalize L4"]
    n2_core_Engine_store --> n9_util_normalize

edges

• Engine.store -> validate @L58

• Engine.store -> normalize @L59

• run_pipeline -> Engine.store @L70

`code_complexity` on the standard library's `argparse`:

complexity /usr/lib/python3.11/argparse.py [138 functions, module total 350]

average 3.7 max 46 functions over 10: 10

function lines cc rank len depth

ArgumentParser._parse_known_args L1930-2187 46 F 258 6 HelpFormatter._format_actions_usage L406-519 28 D 114 5

## Development

```bash
pip install -e ".[dev]"

# unit tests
pytest

# end-to-end: spawn the real server and drive it over stdio with a
# handwritten JSON-RPC client (initialize -> tools/list -> tools/call)
python scripts/stdio_smoke_test.py

Layout:

src/py_ast_mcp/
  server.py        MCP tool registration (FastMCP, stdio transport)
  parse.py         shared parse + cache by path/mtime/size, AST navigation
  format.py        shared output formatting
  analyze.py       analyze_file, analyze_package, find_node_at_position
  functions.py     list_functions, get_function_body, list_methods
  types.py         get_type_definition, list_declarations
  imports.py       list_imports, list_exports
  usages.py        find_usages
  callgraph.py     call_graph, get_callers
  complexity.py    code_complexity
  smells.py        code_smells
  errors.py        find_errors
  deadcode.py      dead_code
  protocols.py     find_implementations
  doc.py           get_doc
  diff.py          diff_ast
  jedi_support.py  optional cross-file resolution

Known limitations

These are heuristics over a syntax tree, not a type checker:

• The server parses with its own interpreter's grammar. ast can only read syntax the running Python understands, so a server on 3.11 reports PEP 695 code (type X = ..., def f[T]()) as a syntax error even though the file is valid. Run the server on the newest Python you have, regardless of what the target project targets — parse errors say so when the interpreter may be the cause.

• Call resolution is name-based. obj.method() is matched by method name; when several classes in scope define the same name the first one wins. self.method() resolves within the enclosing class and then across classes in the file.

• Cross-module call edges in scope="package" are resolved through import statements only. Dynamic dispatch, factories and callbacks are not followed.

• dead_code matches by name, not by scope. getattr, plugin registries, entry points and re-exports from outside the scan produce false positives; public symbols are reported separately as lower confidence. The larger risk is the other direction: any attribute access or string literal sharing a symbol's name marks it live, so the tool under-reports. Treat hits as candidates to confirm.

• jedi resolution is scoped to the detected project root, found by walking up for .git / setup.py / requirements.txt. Files outside that root are invisible to find_usages' cross-file section.

• unawaited-coroutine is best effort. It flags calls to async def functions declared in the same file that are neither awaited nor wrapped in a recognised asyncio helper.

• Inherited members are only resolved for base classes defined in the same file; bases from other modules are listed as unresolved.

• list_declarations type inference is literal-shaped, not a real inference engine: it reports what a reader would infer from the right-hand side.

License

MIT