codebase-mcp

Overview

Codebase MCP is an open-source development assistant that integrates with Claude Desktop through the Model Context Protocol. It provides 13 specialized tools for codebase management, including semantic search, persistent memory, intelligent code writing with auto-formatting, and session-based Git workflows. The system operates locally with minimal cloud dependencies, using only Google's Gemini API for AI-assisted editing operations. It's designed as a free alternative to paid coding assistants like Cursor, leveraging an existing Claude subscription.

Try asking AI

After installing, here are 5 things you can ask your AI assistant:

• session_tool

  Manage development sessions with automatic branch creation and commits

  Try:Create a new session for the payment featureTry:Check my current session status
• memory_tool

  Store and retrieve persistent knowledge across chat sessions

  Try:Remember that I use async/await patternsTry:Show me previous mistakes I've made
• git_tool

  Perform Git operations including status, diff, commit and branch management

  Try:Show me the changes in this branchTry:Commit these changes with a descriptive message
• write_tool

  Create new files with auto-formatting and quality scoring

  Try:Create a new user authentication moduleTry:Write a test file for the payment processor
• edit_file

  AI-assisted file editing with Gemini-powered suggestions

  Try:Refactor this function to use dependency injectionTry:Fix the bug in this authentication logic
• search_tool

  Perform semantic code search across the entire codebase

  Try:Find all user-related functionsTry:Search for database connection patterns
• read_code_tool

  Read code with symbol-level precision and line range support

  Try:Read the entire UserService classTry:Show me lines 10-25 of the payment processor
• project_context_tool

  Analyze project structure and dependencies

  Try:Give me an overview of this projectTry:Identify all third-party dependencies
• list_directory_tool

  Explore directory structures with tree views and metadata

  Try:Show me the src directory structureTry:List all Python files in the project
• code_analysis_tool

  Perform code quality checks including syntax, linting and dependencies

  Try:Check this file for linting issuesTry:Analyze the code quality of the auth module
• list_file_symbols_tool

  Extract functions, classes and interfaces from source files

  Try:List all symbols in this fileTry:Show me all public methods in the Service class
• project_structure_tool

  Visualize project structure with enhanced tree views and statistics

  Try:Visualize the entire project structureTry:Show me a breakdown of file types and sizes

Comparable tools

Installation

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

# 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
pip install black ruff

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

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

python main.py /path/to/your/project

FAQ

How does Codebase MCP compare to Cursor?

Codebase MCP is an open-source alternative that uses your existing Claude subscription instead of requiring a separate $20-40/month fee. It provides similar features like semantic search and AI-assisted editing while being privacy-first with local processing.

What data is sent to external services?

Only the edit_file tool uses Google's Gemini API, and only sends the specific file being edited (no project context or history). All other operations including embeddings, search, and memory processing run locally on your machine.

Compare codebase-mcp with