python-mcp-server

MCP (Model Context Protocol) server for deterministic static analysis of Python code, built with LibCST + Jedi.

Motivation

This project is inspired by the deterministic analysis approach of cobol-mcp-server. Just as that project demonstrates that COBOL can be analyzed deterministically via AST (without AI), python-mcp-server applies the same principle to the Python ecosystem:

• LibCST — parses source code into a concrete AST, guaranteeing 100% deterministic analysis (no guesswork).
• Jedi — optional type resolution for finding definitions and references (on-demand, no classpath required).
• No code execution — only static syntax analysis.

The result is an MCP server that exposes Python code analysis tools to any MCP client (OpenCode, Claude Desktop, etc.).

Tools

Tool	Description
load_python_project	Loads a project from local path, Git URL, or archive (.zip/.tar.gz)
unload_python_project	Removes a loaded project from memory
list_loaded_projects	Lists all projects currently in memory
project_metadata	Shows project metadata (build, modules, classes, functions)
detect_build_system	Detects the build system (pip, poetry, pdm, hatch, uv, conda, etc.)
detect_framework	Detects frameworks/libs in use (Flask, Django, FastAPI, SQLAlchemy, etc.)
list_modules	Lists all Python modules in the project
list_classes	Lists all classes in the project
list_functions	Lists all functions and methods in the project
inspect_class	Deep-dives into a class: bases, methods, decorators, docstring
inspect_function	Deep-dives into a function: signature, parameters, body, decorators
list_imports	Lists all imports in the project
list_decorators	Lists all decorators used with their frequencies
find_decorated_elements	Finds classes/functions decorated with a specific decorator
class_hierarchy	Shows inheritance hierarchy (bases and direct subclasses)
search_source	Searches text in the project source code
multi_file_search	Searches text across all loaded projects simultaneously
find_definition	Finds the definition of a symbol (requires type_resolution=True)
find_references	Finds references to a symbol (requires type_resolution=True)
get_file_content	Reads the raw source content of any file in the project
get_source_range	Returns specific source lines with line numbers from a file
validate_code_reference	Checks if a class, function, or variable exists (EXISTS/NOT_FOUND)
resolve_type	Resolves a type name to its definition, tracing imports across the project
inspect_module	Deep-dives into a module: docstring, variables, functions, classes, imports
call_chain	Static call graph: shows which functions are called and which call a given function
variable_xref	Cross-references a variable: shows declarations, writes, and reads across the project
list_enums	Lists all enum classes with their members and values
module_dependency_graph	Builds a dependency map showing which modules import which
list_methods_by_return_type	Finds all functions/methods that return a specific type annotation
find_entry_points	Finds where the program starts: if name, console_scripts, web apps, CLI apps, async runners
list_api_endpoints	Lists all API route/endpoint definitions (FastAPI, Flask, Starlette, Django) with paths and handlers
extract_environment_dependencies	Extracts environment variable reads, config file loads, and Pydantic Field(env=...)
list_side_effects	Classifies functions by side effects: FILE_IO, NETWORK, DB, LOG, MUTATION, or PURE
analyze_error_handling	Analyzes error handling: custom exceptions, raises, try/except patterns, bare excepts
list_public_api	Shows the public API surface: all, init.py re-exports, top-level public definitions
find_test_mapping	Maps production code to tests by analyzing test file imports
extract_domain_vocabulary	Extracts domain-specific vocabulary — key entities, module docstrings, domain terms

Building the .pyz (fat-pyz)

Important: shiv must be installed in the Python interpreter that you use to build the wheel. The resulting .pyz will then be runnable on any Python 3.8+ system interpreter, but the build itself must be done with a Python version you want to ship wheels for.

The package layout is src/pymcp/ (declared in pyproject.toml via setuptools.packages.find), so shiv discovers it automatically when run from the project root.

Build inside a venv (recommended)

# 1. Create / activate a venv (use any Python 3.8+ interpreter)
python -m venv .venv
source .venv/bin/activate

# 2. Install build tooling
pip install shiv

# 3. Build the fat .pyz from the project root
shiv -o python-mcp-server.pyz -e pymcp.main:main -p "/usr/bin/env python3" .

For reproducible builds, create the venv with a pinned interpreter, e.g. python3.11 -m venv .venv. This guarantees the bundled wheels match the target Python's ABI.

Why this matters

• shiv resolves dependencies via pip, which downloads wheels built for the active interpreter's ABI (e.g. cp311 for Python 3.11).
• If you build with Python 3.14 and try to run the .pyz with the system's Python 3.11, you'll get zipimport.ZipImportError because the bundled cp314 wheels are not compatible.
• The pyproject.toml pins requires-python = ">=3.8". Make sure the Python used to build the .pyz is the same major.minor you intend to run it with.

Smoke test

./python-mcp-server.pyz   # starts the MCP server on stdio and logs to /tmp/python_mcp_server.log

The resulting .pyz is standalone — it includes all dependencies (mcp, libcst, jedi, GitPython) and works with any Python 3.8+ interpreter.

You can also run the installed entrypoint directly:

python-mcp-server

OpenCode Configuration

Add the following to your opencode.json or opencode.yml:

{
  "mcpServers": {
    "python-mcp-server": {
      "command": "python",
      "args": ["python-mcp-server.pyz"],
      "transport": "stdio"
    }
  }
}

Or if installed as a package:

{
  "mcpServers": {
    "python-mcp-server": {
      "command": "python-mcp-server",
      "transport": "stdio"
    }
  }
}

Environment Variables

Variable	Default	Description
PYMCP_LOG_FILE	/tmp/python_mcp_server.log	Log file path
PYMCP_LOG_LEVEL	INFO	Log level (DEBUG, INFO, WARNING, ERROR)

Dependencies

• mcp >= 1.0.0
• libcst >= 1.0.0
• jedi >= 0.19.0
• GitPython >= 3.1.0

License

MIT — see LICENSE.