home / mcp / python mcp server

Python MCP Server

Provides a Python-based MCP server that extracts import relationships and contextual code for code graph analysis.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "hesiod-au-python-mcp": {
      "command": "python",
      "args": [
        "run_server.py"
      ]
    }
  }
}

You run a Python MCP Server to extract and analyze code graphs, focusing on how files import and reference each other. This server helps you surface only relevant code, includes nearby context from the same directory, and formats results for seamless use with MCP clients and large language models.

How to use

Launch the server locally and connect to it from your MCP client. The server exposes a focused Python code extraction tool that analyzes a target file, discovers its imports, classes, and functions, and returns the complete code of the target along with related files from the same directory. You can request the tool to pull additional contextual files to enrich the analysis while respecting token limits. Use this to build a code graph that shows how modules depend on one another and to inspect how documents and readmes accompany codebases.

How to install

Prerequisites: you need Python installed on your system. You may also want a virtual environment to isolate dependencies.

Step by step commands you should run in your terminal:

# Clone the project (adjust to the actual path)
git clone https://github.com/hesiod-au/python-mcp
cd python-mcp

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows, use: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Configuration and usage notes

Configure the MCP client to connect to the Python MCP Server as a local stdio process. The client runs the server via Python and passes the server script path as an argument. You can also supply an environment variable to set the maximum token limit for extraction.

"mcpServers": {
  "python-code-explorer": {
    "command": "python",
    "args": [
      "/path/to/python-mcp-new/server.py"
    ],
    "env": {
      "TOKEN_LIMIT": "8000"
    }
  }
}

Notes on usage and context

- The tool returns a structured result that includes the target file, any referenced files, and additional files from the same directory for better context. It also reports the total token usage and token limit so you can adjust the scope of extraction.

- You can customize the token limit by setting TOKEN_LIMIT in your client configuration. The default shown here is 8000.

Example environment and commands for development and testing

Start the server in a typical development setup using a script named run_server.py or a dedicated server script as described in your configuration.

# Start the server with default settings
python run_server.py

# Start with a custom name (if supported by your setup)
python run_server.py --name "My Code Explorer"

# Use a specific environment file
python run_server.py --env-file .env.production

Troubleshooting tips

If you encounter file-not-found errors for the target or referenced files, verify the paths you provided and ensure the server has access to those files. Check that the token limit does not overwhelm the language model you are using and adjust TOKEN_LIMIT as needed.

Available tools

get_python_code

Return the code of a target Python file and related files based on import/export proximity.