Python Code Explorer MCP server

The Python MCP Server provides powerful tools for extracting and analyzing Python code structures, focusing on import/export relationships between files. This lightweight implementation doesn't require an agent system, making it easy to integrate into any Python application while maintaining compatibility with the Model Context Protocol JSON-RPC standard.

Installation

# Clone the repository
git clone https://github.com/yourusername/python-mcp-new.git
cd python-mcp-new

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

# Install dependencies
pip install -r requirements.txt

Environment Configuration

Create a .env file based on the provided .env.example:

# Token limit for extraction
TOKEN_LIMIT=8000

Configuring for MCP Clients

To configure this MCP server for use in MCP-compatible clients (like Codeium Windsurf), add the following configuration to your client's MCP config file:

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

Replace /path/to/python-mcp-new/server.py with the absolute path to the server.py file on your system.

Usage Examples

Direct Function Call

You can use the get_python_code function directly in your Python code:

from agent import get_python_code

# Get Python code structure for a specific file
result = get_python_code(
    target_file="/home/user/project/main.py",
    root_repo_path="/home/user/project"  # Optional, defaults to target file directory
)

# Process the result
target_file = result["target_file"]
print(f"Main file: {target_file['file_path']}")
print(f"Docstring: {target_file['docstring']}")

# Display related files
for ref_file in result["referenced_files"]:
    print(f"Related file: {ref_file['file_path']}")
    print(f"Object: {ref_file['object_name']}")
    print(f"Type: {ref_file['object_type']}")

# See if we're close to the token limit
print(f"Token usage: {result['token_count']}/{result['token_limit']}")

Using the MCP Protocol

Listing Available Tools

from agent import handle_mcp_request
import json

# List available tools
list_request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list"
}

response = handle_mcp_request(list_request)
print(json.dumps(response, indent=2))

Calling get_python_code Tool

from agent import handle_mcp_request
import json

# Call the get_python_code tool
tool_request = {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
        "name": "get_python_code",
        "arguments": {
            "target_file": "/home/user/project/main.py",
            "root_repo_path": "/home/user/project"  # Optional
        }
    }
}

response = handle_mcp_request(tool_request)
print(json.dumps(response, indent=2))

Handling Errors

from agent import handle_mcp_request

# Call with invalid file path
faulty_request = {
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
        "name": "get_python_code",
        "arguments": {
            "target_file": "/path/to/nonexistent.py"
        }
    }
}

response = handle_mcp_request(faulty_request)
print(json.dumps(response, indent=2))

Using the MCP SDK Server

This project includes a full-featured Model Context Protocol (MCP) server built with the official Python MCP SDK. The server exposes the code extraction functionality in a standardized way that can be used with any MCP client, including Claude Desktop.

Starting the Server

python server.py

Using the MCP Development Mode

With the MCP SDK installed, you can run the server in development mode using the MCP CLI:

mcp serve --command "python server.py"

This will start the MCP Inspector, a web interface for testing and debugging your server.

Claude Desktop Integration

You can configure Claude Desktop to use your MCP server by adding the configuration shown earlier to your Claude Desktop MCP config file.

Response Format Details

The get_python_code tool returns a structured JSON object with the following key fields:

• target_file: Information about the target Python file
• referenced_files: List of objects imported by the target file
• additional_files: Additional context files from the same directory
• total_files: Total number of files included in the response
• token_count: Approximate count of tokens in all included code
• token_limit: Maximum token limit configured for extraction

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect