⚠️ Platform Support Notice

This MCP server has been tested on macOS and Linux. Windows support is currently unverified (not yet tested).

If you try Windows and encounter issues, please open an issue so we can improve cross-platform support.

Code Understanding MCP Server

An MCP (Model Context Protocol) server designed to understand codebases and provide intelligent context to AI coding assistants. This server handles both local and remote GitHub repositories and supports standard MCP-compliant operations.

🤖 AI Assistant Installation

Have an AI coding assistant help you install this server! Copy and paste the contents of our Setup Assistant Prompt to your AI assistant (Claude, ChatGPT, Cursor, etc.) and it will guide you through the entire installation process.

Features

• Clone and analyze GitHub repositories or local codebases
• Get repository structure and file organization
• Identify critical files based on complexity metrics and code structure
• Generate detailed repository maps showing:
  • Function signatures and relationships
  • Class definitions and hierarchies
  • Code structure and dependencies
• Retrieve and analyze repository documentation
• Target analysis to specific files or directories
• Keep analysis up-to-date with repository changes via refresh

Quick Start: MCP Client Configuration

Prerequisites

Required: uv Installation

This server requires uv, a modern Python package manager. If you don’t already have uv installed:

# Install UV (macOS/Linux)
curl -sSf https://astral.sh/uv/install.sh | sh

# Install UV (Windows PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

For more installation options, visit the official uv installation guide at astral.sh/uv.

Installation Methods

Method 1: Direct execution with uvx (Recommended)

# Run directly without installing a global binary
uvx code-understanding-mcp-server

This launches the server in an isolated environment managed by UV each time.

Method 2: Virtual environment install (Optional)

If you prefer a persistent binary inside a dedicated virtual environment:

# Create a dedicated virtual environment
uv venv ~/.venvs/mcp-code-understanding

# Activate it (macOS/Linux)
source ~/.venvs/mcp-code-understanding/bin/activate

# Install the package into the venv
uv pip install code-understanding-mcp-server

# Run the server
code-understanding-mcp-server

Verify Installation

Depending on your chosen method:

# Method 1 (uvx): runs via uvx; no persistent binary is installed
uvx --version

# Method 2 (venv install): verify the binary inside your venv
which code-understanding-mcp-server
# Expected output example: /Users/username/.venvs/mcp-code-understanding/bin/code-understanding-mcp-server

Configure Your MCP Client

Use one of the following configurations for your MCP client:

{
  "mcpServers": {