Privacy-first AI development assistant via MCP | Turn Claude into your personal coding assistant | Semantic code search • AI-assisted editing • Quality-checked generation • Persistent memory | Free open-source alternative to Cursor & paid AI coding tools | Python, React, TypeScript, FastAPI

Open Source**

License Python MCP Version

Codebase MCP is an open-source AI-powered development assistant that connects Claude Desktop (or any MCP-compatible LLM) to your codebase through the Model Context Protocol. Stop paying for separate coding assistants - if you already have a Claude subscription, that's all you need.

📖 Read Full Documentation | 🏗️ Architecture | 🤝 Contributing

Modern AI coding assistants like Cursor, Windsurf, and others charge 20ドル-40+/month on top of your existing LLM subscription. If you already pay for Claude, why pay again for a coding assistant?

Codebase MCP turns your existing Claude subscription into a powerful coding assistant:

• ✅ One subscription - Use your existing Claude Pro/Team plan
• ✅ Privacy-first - Local embeddings and processing (except edit operations)
• ✅ Open source - Apache 2.0 license, community-driven
• ✅ Extensible - Works with any MCP-compatible LLM via Model Context Protocol
• ✅ Lightweight - ~100MB memory footprint for medium projects
• ✅ Fast - Sub-second semantic search with local FAISS indexing

• Python 3.11+
• Claude Desktop (or any MCP-compatible client)
• Git installed
• uv package manager (recommended)

1. Clone the repository:

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

2. Install globally (recommended):

# Install uv if you haven't
pip install uv
# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -r requirements.txt
# Install formatters globally (required for code formatting)
pip install black ruff

3. Configure Gemini API (for edit tool):

# Create .env file
cp .env.example .env
# Get free API key from: https://aistudio.google.com/app/apikey
# Add to .env:
GEMINI_API_KEY=your_api_key_here

4. Configure Claude Desktop:

Add to your claude_desktop_config.json:

{
 "mcpServers": {
 "codebase-manager": {
 "command": "/path/to/your/.venv/bin/python",
 "args": [
 "/path/to/codebase-mcp/mcp_server.py"
 ]
 }
 }
}

5. Start the FastAPI server:

# In a separate terminal, navigate to your project directory
python main.py /path/to/your/project
# Server starts on http://localhost:6789
# You can access the web dashboard at: http://localhost:6789

6. Use with Claude Desktop:

• Restart Claude Desktop
• Start chatting - Claude now has access to 13+ MCP tools for codebase management!

• AI-powered code understanding with local embeddings
• Multi-language support (Python, JavaScript, TypeScript)
• Symbol-level indexing (functions, classes, interfaces)
• Fuzzy search and exact matching modes

• Remember context across chat sessions
• Categorize learnings: progress, mistakes, solutions, architecture
• Semantic memory search with importance scoring
• Never repeat the same mistake twice

• Isolated development branches for each feature
• Automatic commit tracking in .codebase directory
• Separate from user's .git - track AI changes independently
• Auto-merge support with quality gates

• Write Tool: Create new files with auto-formatting and quality scoring
• Edit Tool: AI-assisted editing with Gemini integration (inspired by Cursor)
• Quality Gates: Auto-commit only when code quality ≥ 80%
• Dependency Checking: Prevent code duplication and missing imports

• Python: Black + Ruff (PEP 8 compliant)
• TypeScript/JavaScript: Prettier + ESLint
• Quality Scoring: Automatic code quality assessment
• Error Recovery: Intelligent retry with corrections

• Real-time codebase analysis
• File structure visualization
• Dependency tracking
• Symbol extraction and indexing

┌─────────────────┐
│ Claude Desktop │ User interacts via chat
└────────┬────────┘
 │ MCP Protocol (stdio)
 ↓
┌─────────────────┐
│ MCP Server │ 13+ Tools (proxy layer)
│ (mcp_server.py)│ Lightweight, fast
└────────┬────────┘
 │ HTTP/REST
 ↓
┌─────────────────┐
│ FastAPI Server │ Port 6789 (main.py)
│ Core Engine │ 40+ API endpoints
└────────┬────────┘
 │
 ┌────┴─────┬─────────┬──────────┐
 ↓ ↓ ↓ ↓
┌────────┐ ┌──────┐ ┌────────┐ ┌───────────┐
│Semantic│ │Memory│ │ Git │ │Code Tools │
│ Search │ │System│ │Manager │ │ Pipeline │
└────────┘ └──────┘ └────────┘ └───────────┘
 │ │ │ │
 └──────────┴─────────┴──────────┘
 ↓
 ┌──────────────────────┐
 │ Local Storage │
 │ • FAISS (vectors) │
 │ • SQLite (metadata) │
 │ • .codebase (git) │
 └──────────────────────┘

Privacy Note: All processing is local except the edit tool, which uses Google's free Gemini API for AI-assisted code editing. Only the edited file is sent to Gemini - no project context or history.

View Detailed Architecture Diagram

Codebase MCP provides 13 specialized MCP tools for comprehensive development automation:

• Semantic Search: Sub-second response for typical codebases
• Memory Footprint: ~100MB for medium projects (<20k lines)
• Indexing Speed: ~30 seconds for 10k lines initial index
• Edit Operations: 5-15 seconds (Gemini API + formatting)
• Optimal Project Size: <20,000 lines (tested and verified)

Note: Edit tool can be slow due to Gemini API latency and code formatting. Claude Desktop may timeout on very large edits (use smaller, focused edits).

User: "Create a FastAPI endpoint for user authentication with JWT tokens"
Claude:
✅ Searching for existing auth patterns...
✅ Creating session: feat/user-auth
✅ Writing authentication.py with JWT implementation
✅ Auto-formatted with Black + Ruff
✅ Quality score: 95% - Auto-committed
✅ Storing solution in memory

User: "Refactor the user service to use dependency injection"
Claude:
✅ Reading current user service implementation
✅ Searching for DI patterns in codebase
✅ Editing with AI assistance (Gemini)
✅ Validating changes with quality gates
✅ Session: refactor/user-di ready for review

User: "Continue working on the payment integration"
Claude:
✅ Loading memory context...
✅ Found previous progress: Stripe API setup complete
✅ Found previous mistake: Don't use synchronous requests in async endpoints
✅ Continuing from last checkpoint...

• Local Embeddings: AllMiniLM-L6-v2 runs entirely on your machine
• Local Processing: FAISS vector store, SQLite metadata - all local
• No Cloud Dependencies: Except for Gemini API (edit tool only)

• Scope: Only edit_file tool uses Gemini
• Data Sent: Only the file being edited (no project context)
• Alternative: Contributors can add local LLM support (GPU required)
• Cost: Free tier (15 RPM, 250K TPM, 1K RPD)

• Never commit .env with API keys
• Use .gitignore for sensitive files
• Review AI-generated code before production deployment
• Keep dependencies updated

We welcome contributions! This project was built to be community-driven and extensible.

Priority Areas:

• 🌐 Language Support: Add Java, Go, Rust, PHP, etc.
• 🧠 Local LLM Integration: Replace Gemini with local models
• 🔍 Search Improvements: Enhanced semantic algorithms
• 📊 UI/UX: Improve web dashboard
• ⚡ Performance: Optimization for larger codebases

See CONTRIBUTING.md for detailed guidelines.

This project is licensed under the Apache License 2.0 - see LICENSE file for details.

Credits:

• Edit tool techniques inspired by Cursor
• Built with Claude Sonnet 4 and 4.5
• Powered by Model Context Protocol

Current Version: v1.0.0-beta

Upcoming Features:

• Community-driven enhancements
• More language support
• Local LLM alternatives
• Performance optimizations
• Advanced prompt engineering templates

• 📖 Documentation: https://danyqe.github.io/codebase-mcp/
• 🐛 Issues: https://github.com/danyQe/codebase-mcp/issues
• 💬 Discussions: https://github.com/danyQe/codebase-mcp/discussions
• 🌟 Star this repo if you find it useful!

Special thanks to:

• Anthropic for Claude and the Model Context Protocol
• Google for the free Gemini API
• Cursor team for pioneering AI-assisted editing techniques
• Open source community for making this possible

Made with ❤️ by developers, for developers

Stop paying for coding assistants. Start building with your own LLM.