GitHub Get Started

Codebase MCP

Turn any LLM into your personal coding assistant

v1.0.0-beta Apache 2.0 License Python 3.11+ MCP Compatible

Codebase MCP is an open-source, privacy-first AI development assistant that connects your LLM (like Claude) to your codebase through the Model Context Protocol (MCP). Build production-ready applications without expensive coding assistant subscriptions.

🔒
Privacy-First
All processing happens locally except optional AI-assisted editing
💰
Cost-Effective
No additional subscriptions beyond your LLM access
🔌
LLM-Agnostic
Works with any MCP-compatible LLM
🚀
Lightweight
MCP proxy architecture keeps Claude Desktop fast
🧠
Persistent Memory
Context persists across sessions using semantic search
📦
Production-Ready
Built for real-world Python and React development

Why Codebase MCP?

The Problem

Modern AI coding assistants like Cursor and Windsurf are powerful but come with significant costs:

The Solution

Codebase MCP changes the game by turning YOUR existing LLM into a full-featured coding assistant:

💡 Note: The only exception to local-only processing is the optional AI-assisted editing feature, which uses Google's free Gemini API. Only the file being edited is sent to Gemini—no broader project context is shared. Contributors can easily replace this with local LLMs if desired.

Perfect For

Quick Start

Prerequisites

5-Minute Setup

1. Clone & Install

# Clone repository
git clone https://github.com/danyQe/codebase-mcp.git
cd codebase-mcp

# Install using uv (recommended)
pip install uv
uv venv
uv pip install -r requirements.txt

# Install code formatters globally
pip install black ruff

2. Configure Environment

# Create .env file
cp .env.example .env

# Edit .env and add your Gemini API key
GEMINI_API_KEY=your_api_key_here

3. Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "codebase-manager": {
      "command": "C:\\path\\to\\codebase-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\path\\to\\codebase-mcp\\mcp_server.py"
      ]
    }
  }
}
⚠️ Important: Use absolute paths and adjust for your operating system (forward slashes on macOS/Linux, backslashes on Windows).

4. Start FastAPI Server

# Start server with your project directory
python main.py /path/to/your/project

# With auto-reload (development)
python main.py /path/to/your/project --reload

Server runs on http://localhost:6789

5. Restart Claude Desktop

Restart Claude Desktop to load the MCP server. You should now see Codebase MCP tools available!

✅ You're ready! Try asking Claude: "Start a new development session for my project"

Installation

System Requirements

Requirement Minimum Recommended
Python 3.11 3.11+
RAM 4 GB 8 GB+
Storage 500 MB 1 GB+
OS Windows 10 Windows 11 / macOS / Linux

Installation Methods

Method 1: Using uv (Recommended)

# Install uv package manager
pip install uv

# Clone repository
git clone https://github.com/danyQe/codebase-mcp.git
cd codebase-mcp

# Create virtual environment and install
uv venv
uv pip install -r requirements.txt

# Install formatters globally
pip install black ruff

Method 2: Using pip

# Clone repository
git clone https://github.com/danyQe/codebase-mcp.git
cd codebase-mcp

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Install formatters globally
pip install black ruff

Method 3: Docker (Coming Soon)

Docker support is planned for a future release.

Verify Installation

# Test FastAPI server
python main.py /path/to/test/project

# Check if server is running
curl http://localhost:6789/health

Configuration

Environment Variables

Create a .env file in the project root:

# Gemini API Configuration (Required for edit_tool)
GEMINI_API_KEY=your_gemini_api_key_here

# Server Configuration (Optional)
HOST=0.0.0.0
PORT=6789

# Working Directory (Optional - can be set via command line)
WORKING_DIR=/path/to/your/project

# Logging (Optional)
LOG_LEVEL=INFO

Claude Desktop Configuration

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "codebase-manager": {
      "command": "/absolute/path/to/.venv/Scripts/python.exe",
      "args": [
        "/absolute/path/to/mcp_server.py"
      ]
    }
  }
}
⚠️ Path Requirements:
  • Always use absolute paths
  • Windows: Use double backslashes \\ or forward slashes /
  • macOS/Linux: Use forward slashes /
  • Point to the Python executable in your virtual environment

Git Configuration

Codebase MCP uses two separate git directories:

💡 Why separate directories? This separation keeps AI-generated changes organized and doesn't interfere with your personal git workflow. You maintain full control over what gets committed to your actual repository.

Rate Limits (Gemini API)

The free Gemini API tier has the following limits:

Codebase MCP automatically handles rate limiting with exponential backoff.

Tools Overview

Codebase MCP provides 13+ specialized tools accessible via the Model Context Protocol. Each tool is designed for specific development tasks.

Tool Purpose Key Features
session_tool Session management Branch creation, isolation, merging
memory_tool Knowledge persistence Store learnings, search context
git_tool Git operations Status, commit, diff, log, branches
write_tool Intelligent writing Format, quality check, auto-commit
edit_tool AI-assisted editing Gemini-powered, contextual edits
search_tool Code search Semantic, fuzzy, text, symbol search
read_code_tool Read files/symbols Line ranges, symbols, whole files
project_structure_tool Project analysis Structure, dependencies, stats

Tool Categories

🔧 Development Workflow

📝 Code Operations

🔍 Code Discovery

🧠 Intelligence

session_tool

Purpose: Manage isolated development sessions with automatic branching

Operations

Example Usage

# Start a new session
session_tool(operation="start", session_name="feature-user-auth")

# Check current session
session_tool(operation="current")

# End session with auto-merge
session_tool(operation="end", auto_merge=True)

# Delete old session
session_tool(operation="delete", session_name="old-feature")

Best Practices

memory_tool

Purpose: Store and retrieve project knowledge across chat sessions

Operations

Memory Categories

Importance Levels

Example Usage

# Store a learning
memory_tool(
    operation="store",
    category="learning",
    content="Always validate email format before database queries",
    importance=4
)

# Store a mistake
memory_tool(
    operation="store",
    category="mistake",
    content="MISTAKE: Used sync DB calls in async endpoint. CORRECTION: Use async DB session. PREVENTION: Always check if endpoint is async.",
    importance=5
)

# Search memories
memory_tool(
    operation="search",
    query="database optimization techniques",
    max_results=5
)

# Get startup context
memory_tool(operation="context")

Best Practices

write_tool

Purpose: Write new code with automatic formatting, dependency checking, and quality analysis

Features

Parameters

Example Usage

# Write a new Python file
write_tool(
    file_path="api/routes/auth.py",
    content='''
from fastapi import APIRouter, Depends
from pydantic import EmailStr

router = APIRouter()

@router.post("/login")
async def login(email: EmailStr, password: str):
    # Login logic here
    return {"status": "success"}
    ''',
    purpose="User authentication endpoint"
)

Quality Scoring

The quality score is calculated based on:

Score ≥ 0.8 enables auto-commit

edit_tool

Purpose: AI-assisted code editing using Gemini API

💡 Privacy Note: This tool sends only the target file to Gemini API (not the entire codebase). Editing techniques inspired by Cursor.

Features

Parameters

Example Usage

# Edit existing file
edit_file(
    target_file="api/routes/auth.py",
    instructions="Add rate limiting to login endpoint",
    code_edit='''
// ... existing code ...
from slowapi import Limiter
// ... existing code ...
@router.post("/login")
@limiter.limit("5/minute")
async def login(email: EmailStr, password: str):
// ... existing code ...
    '''
)

Best Practices

Timeout Handling

If editing takes >30 seconds, you'll receive a timeout message. This prevents Claude Desktop from timing out. Options:

search_tool

Purpose: Multi-mode code search (semantic, fuzzy, text, symbol)

Search Modes

Mode Use Case Speed
semantic Find code by meaning/intent Fast (<1s)
fuzzy_symbol Find functions/classes by approximate name Very Fast
text Find exact text/regex patterns Fast
symbol_exact Find symbols by exact name Very Fast

Example Usage

# Semantic search
search_tool(
    query="functions that handle user authentication",
    search_type="semantic",
    max_results=10
)

# Fuzzy symbol search
search_tool(
    query="usr_auth",
    search_type="fuzzy_symbol",
    symbol_type="function"
)

# Text search with regex
search_tool(
    query="TODO:|FIXME:",
    search_type="text",
    use_regex=True,
    file_pattern="*.py"
)

Performance

API Reference

Codebase MCP FastAPI server provides 40+ REST endpoints for direct integration.

Base URL

http://localhost:6789

API Categories

Authentication

Currently, the API runs locally without authentication. Future versions may add API key authentication for remote access.

Example API Calls

Health Check

curl http://localhost:6789/health

Search Code

curl -X POST http://localhost:6789/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user authentication",
    "search_type": "semantic",
    "max_results": 5
  }'

Write File

curl -X POST http://localhost:6789/write \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "test.py",
    "content": "print(\"Hello World\")",
    "purpose": "Test file"
  }'

Key Endpoints

Session Endpoints

Endpoint Method Description
/session POST Create/manage sessions
/session/current GET Get current session status
/session/auto-commit POST Auto-commit changes

Memory Endpoints

Endpoint Method Description
/memory/store POST Store new memory
/memory/search POST Search memories
/memory/context GET Get startup context
/memory/stats GET Get statistics
/memory/{id} PUT Update memory

Search Endpoints

Endpoint Method Description
/search POST Semantic search
/search/text POST Text/regex search
/search/symbols POST Symbol search

Architecture

System Overview

Codebase MCP uses a three-tier architecture designed for performance and separation of concerns:

┌─────────────────────┐
│  Claude Desktop     │ (MCP Client)
│  (or any MCP LLM)   │
└──────────┬──────────┘
           │ MCP Protocol
           ↓
┌─────────────────────┐
│   MCP Server        │ (Lightweight Proxy)
│   (mcp_server.py)   │  
└──────────┬──────────┘
           │ HTTP/REST
           ↓
┌─────────────────────┐
│   FastAPI Server    │ (Processing Engine)
│   (main.py)         │
│                     │
│  ┌───────────────┐  │
│  │ API Routers   │  │ → 40+ endpoints
│  ├───────────────┤  │
│  │ Code Tools    │  │ → Write, Edit, Format
│  ├───────────────┤  │
│  │ Semantic      │  │ → FAISS + Embeddings
│  │ Search        │  │
│  ├───────────────┤  │
│  │ Memory System │  │ → SQLite + Vectors
│  ├───────────────┤  │
│  │ Git Manager   │  │ → .codebase/ tracking
│  └───────────────┘  │
└─────────────────────┘

Component Breakdown

1. MCP Server (Proxy Layer)

2. FastAPI Server (Processing Engine)

3. Code Tools

4. Semantic Search Engine

5. Memory System

Data Flow

Write Operation Flow

1. Claude: "Create auth endpoint"
   ↓
2. MCP Server: Convert to write_tool call
   ↓
3. FastAPI: POST /write
   ↓
4. Write Pipeline:
   - Detect language
   - Format code (Black/Ruff/Prettier)
   - Check dependencies
   - Calculate quality score
   ↓
5. Quality ≥ 0.8? Auto-commit to .codebase
   ↓
6. Return: Results + quality metrics
   ↓
7. Claude: Show success + details

Semantic Search Flow

1. Claude: "Find auth functions"
   ↓
2. MCP Server: search_tool(query="auth functions")
   ↓
3. FastAPI: POST /search
   ↓
4. Semantic Search Engine:
   - Generate query embedding
   - FAISS vector search
   - Retrieve top K results
   - Enrich with metadata
   ↓
5. Return: Ranked results with context
   ↓
6. Claude: Format and present to user

Storage Structure

Project Directory

your-project/
├── .git/              # Your personal git repo
├── .codebase/         # AI-tracked changes
│   ├── HEAD
│   ├── objects/
│   └── refs/
├── .data/             # Codebase MCP data
│   ├── metadata.db    # SQLite: symbols, files
│   └── vectors.faiss  # FAISS: embeddings
├── src/               # Your source code
└── ...

Why Separate .codebase/?

Performance Characteristics

Operation Typical Time Notes
Semantic Search <1 second For <20K lines
Write Tool 1-3 seconds Includes formatting
Edit Tool 5-15 seconds Gemini API call
Memory Search <0.5 seconds Fast vector lookup
Initial Indexing ~30 seconds For 10K lines

Scalability

Prompt Engineering

Codebase MCP includes an optimized system prompt for development workflows. The prompt is exposed as an MCP prompt accessible to Claude.

System Prompt Philosophy

The system prompt configures Claude as an "Elite Solo Software Developer" with complete autonomy over standard development tasks. Key principles:

Workflow Loop

The prompt enforces a 5-phase workflow:

GATHER → PLAN → BUILD → VERIFY → FINALIZE

Phase 1: GATHER Intelligence

Phase 2: PLAN Architecture

Phase 3: BUILD Systematically

Phase 4: VERIFY Rigorously

Phase 5: FINALIZE & Learn

Effective Prompts

✅ Good Prompts (Action-Oriented)

# Clear goal, let Claude handle details
"Create a user authentication system with JWT tokens"

# Specific but not micromanaging
"Add rate limiting to the login endpoint using SlowAPI"

# Leverages context
"Refactor the database queries to use async properly"

# Trusts autonomy
"Fix the bugs in the payment processing module"

❌ Avoid (Too Prescriptive)

# Don't micromanage implementation
"First read auth.py lines 10-50, then search for JWT, 
then write a new function called validate_token_v2..."

# Don't ask for permission on standard tasks
"Can you please maybe consider possibly adding 
some error handling if that's okay?"

# Don't specify tool usage
"Use the write_tool to create a file and then 
use the git_tool to commit it..."

Domain-Specific Tips

Backend Development (FastAPI/Python)

Frontend Development (React/TypeScript)

Refactoring

Debugging

Accessing the System Prompt

The system prompt is available as an MCP prompt:

# In Claude, use the prompt
@system-prompt

# Or ask Claude to use it
"Use the system prompt to guide your development approach"

Best Practices

Session Management

Memory System

Code Quality

Search & Discovery

AI-Assisted Editing

Project Organization

Performance Tips

Examples

Example 1: Create New Feature

Scenario: Building User Authentication

# 1. Start session
"Start a development session for user authentication feature"

# 2. Search for existing patterns
"Find all authentication-related code in the codebase"

# 3. Create backend endpoint
"Create a FastAPI endpoint for user login with email/password validation"

# 4. Create frontend component
"Create a React login form component with TypeScript and form validation"

# 5. Test and commit
"Check the current session status and show me what's been changed"

# 6. Store learning
"Store this learning: User auth requires rate limiting on login attempts"

# 7. End session
"End the session and merge changes to main"

Example 2: Debug Existing Code

Scenario: Fixing Async Database Bug

# 1. Search for problem area
"Find all database query functions in the user service"

# 2. Analyze the issue
"Read the get_user_by_email function from user_service.py"

# 3. Fix the bug
"Edit user_service.py to make the database queries properly async"

# 4. Store mistake
"Store this mistake: Used sync DB calls in async endpoint. 
Always use AsyncSession for database operations."

# 5. Verify fix
"Show git diff for user_service.py"

Example 3: Refactor Code

Scenario: Extract Reusable Validation Logic

# 1. Find duplicate code
"Search for email validation logic across the codebase"

# 2. Plan refactoring
"I want to extract email validation into a reusable utility. 
Search for existing validation utilities."

# 3. Create utility
"Create a validation utility module with email, phone, 
and password validation functions"

# 4. Update existing code
"Update the user registration endpoint to use the new 
validation utility"

# 5. Store solution
"Store this solution: Centralized validation utilities 
prevent code duplication and ensure consistency"

Example 4: Add Feature to Existing File

Scenario: Adding Rate Limiting

# 1. Read current implementation
"Show me the login endpoint in auth_routes.py"

# 2. Edit with AI assistance
"Edit auth_routes.py to add rate limiting using SlowAPI. 
Limit login attempts to 5 per minute per IP address."

# 3. Check quality
"Show me the quality score and any warnings for auth_routes.py"

# 4. Commit if good
"If quality is above 0.8, commit the changes"

Example 5: Start New Project

Scenario: Create FastAPI Boilerplate

# 1. Create project structure
"Create a FastAPI project structure with:
- main.py (entry point)
- api/routes/ (routers)
- services/ (business logic)
- models/ (Pydantic models)
- config.py (configuration)
Include proper async patterns and dependency injection"

# 2. Store architecture decision
"Store this architecture: Using Clean Architecture with 
FastAPI - separate routers, services, and data layers 
for maintainability"

# 3. Create initial endpoint
"Create a health check endpoint at /health"

# 4. Set up session tracking
"Start a session called 'project-init' for this work"

Example 6: Complex Multi-Step Task

Scenario: Add Payment Processing

# 1. Start session
"Start a session for payment-processing feature"

# 2. Load context
"Load memory context about payment requirements"

# 3. Search existing integrations
"Search for any existing payment or API integration code"

# 4. Create service layer
"Create a payment service that integrates with Stripe:
- Initialize Stripe client
- Create payment intent
- Confirm payment
- Handle webhooks
Include proper error handling and logging"

# 5. Create API endpoints
"Create FastAPI endpoints for:
- POST /payments/create (create payment intent)
- POST /payments/confirm (confirm payment)
- POST /webhooks/stripe (handle Stripe webhooks)
Include Pydantic models and proper status codes"

# 6. Add frontend
"Create a React payment form component that:
- Collects card details
- Calls the payment API
- Shows loading and error states
- Handles success/failure"

# 7. Store learnings
"Store these learnings:
1. Always validate Stripe webhook signatures
2. Use idempotency keys for payment retries
3. Log all payment events for audit"

# 8. Review and commit
"Show session status and commit high-quality changes"

Troubleshooting

Common Issues

Issue: MCP Server Not Loading in Claude Desktop

Symptoms: Tools don't appear in Claude Desktop after restart

Solutions:

Issue: FastAPI Server Won't Start

Symptoms: Error when running python main.py

Solutions:

Issue: Gemini API Errors

Symptoms: Edit tool fails with API errors

Solutions:

Issue: Edit Tool Times Out

Symptoms: Edit operations take >30 seconds

Solutions:

Issue: Semantic Search Returns No Results

Symptoms: Search finds nothing despite code existing

Solutions:

Issue: Quality Score Always Low

Symptoms: Write tool reports quality < 0.8

Solutions:

Issue: Session Branch Conflicts

Symptoms: Can't switch or merge session branches

Solutions:

Issue: Memory Not Persisting

Symptoms: Memories disappear after restart

Solutions:

Performance Issues

Slow Semantic Search

High Memory Usage

Getting Help

Contributing

Codebase MCP is open source and welcomes contributions! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

Ways to Contribute

🐛 Report Bugs

💡 Suggest Features

📝 Improve Documentation

🔧 Submit Code

Priority Areas

We're especially interested in contributions for:

1. Language Support

2. Local LLM Integration

3. Semantic Search Improvements

4. UI/UX Enhancements

5. Testing & Quality

Development Setup

# Fork and clone
git clone https://github.com/YOUR_USERNAME/codebase-mcp.git
cd codebase-mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows

# Install dependencies + dev dependencies
pip install -r requirements.txt
pip install pytest pytest-asyncio black ruff mypy

# Run tests
pytest

# Run linters
black .
ruff check .
mypy .

Code Guidelines

Pull Request Process

  1. Create a descriptive branch name: feature/add-java-support
  2. Write clear commit messages
  3. Ensure all tests pass
  4. Update README/docs if needed
  5. Submit PR with detailed description
  6. Respond to review feedback

Code of Conduct

We're committed to providing a welcoming and inclusive environment. Please be respectful and constructive in all interactions.

See CONTRIBUTING.md for full guidelines.

Development Setup

Detailed development environment setup for contributors.

Prerequisites

Full Development Environment

# Clone your fork
git clone https://github.com/YOUR_USERNAME/codebase-mcp.git
cd codebase-mcp

# Add upstream remote
git remote add upstream https://github.com/danyQe/codebase-mcp.git

# Create and activate virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install all dependencies
pip install -r requirements.txt

# Install development tools
pip install pytest pytest-asyncio pytest-cov black ruff mypy pre-commit

# Install pre-commit hooks (optional)
pre-commit install

# Run full test suite
pytest --cov=. --cov-report=html

# Start dev server with auto-reload
python main.py /path/to/test/project --reload

Running Tests

# Run all tests
pytest

# Run specific test file
pytest tests/test_write_tool.py

# Run with coverage
pytest --cov=. --cov-report=html

# Run specific test
pytest tests/test_write_tool.py::test_quality_score

Code Quality Checks

# Format code
black .

# Check linting
ruff check .

# Type checking
mypy .

# Fix auto-fixable issues
ruff check --fix .

Roadmap

Current Version: v1.0.0-beta

Near Term (v1.1.0)

Mid Term (v1.2.0 - v1.5.0)

Long Term (v2.0.0+)

Want to contribute to the roadmap? Open an issue or join development!