MCP Python Code Navigation Server

This project provides a powerful MCP (Model Context Protocol) server for Python that enhances AI-driven development by offering advanced code navigation, analysis, and refactoring capabilities.

Features

The server provides a suite of tools to understand and manipulate Python codebases:

• Find Definition: Locate the definition of a symbol (variable, function, class, etc.).
• Find References: Find all references to a symbol across the project.
• Document Symbols: List all symbols (classes, functions, methods) in a given file.
• Organize Imports: Automatically sort and format import statements.
• Rename Symbol: Safely rename a symbol and all its references.
• Import Graph: Visualize the import relationships between modules.
• And more...: Check out the src/mcp_pytools/tools directory for a full list of available tools.

Getting Started

Prerequisites

• Python 3.10+
• uv (recommended for environment management)

Installation

1. Clone the repository:

   git clone https://github.com/user/mcp_python.git # Replace with the actual URL
   cd mcp_python

2. Create a virtual environment and install dependencies:

   uv venv
   source .venv/bin/activate
   uv pip install -e ".[dev]"

Running the Server

To run the MCP server, use the mcp-pytools-server command. You can optionally provide a path to the root of the Python project you want to analyze. If no path is given, it will default to the current directory.

mcp-pytools-server [PROJECT_ROOT_PATH]

Example:

To run the server for a project located at ~/code/my-python-project:

mcp-pytools-server ~/code/my-python-project

Configuring IDEs and Editors

To use this server with your favorite AI-powered editor, you need to configure it as an MCP server. Here are examples for some popular clients.

Note: You must use the absolute path to the mcp-pytools-server executable, which is located in your virtual environment's bin directory (e.g., /path/to/your/project/.venv/bin/mcp-pytools-server).

Gemini CLI / Claude Code / etc.

Create or edit your MCP configuration file (e.g., ~/.config/gemini/mcp.json or ~/.cursor/mcp.json) and add the following entry. This example sets up the server for a project located at ~/code/my-python-project.

{
  "mcpServers": {
    "python-code-tools": {
      "command": "/path/to/your/project/.venv/bin/mcp-pytools-server",
      "args": [
        "/path/to/your/project/src"
      ],
      "description": "MCP server for Python code navigation and refactoring."
    }
  }
}

Replace /path/to/your/project/.venv/bin/mcp-pytools-server with the actual absolute path to the server executable in your virtual environment and /path/to/your/project/src with the path to the code you want to analyze.

Usage Tips

Once the server is running and your editor is configured, you can start using its capabilities through natural language prompts. Here are some examples of what you can ask your AI assistant:

• "Find the definition of the ServerContext class."
• "Where is the create_tool_handler function used?"
• "Rename the handler variable to tool_handler in server.py."
• "List all the functions in src/mcp_pytools/tools/find_definition.py."
• "Clean up the imports in src/mcp_pytools/server.py."

The server will process these requests and, with your confirmation, perform the corresponding actions on your codebase.