codebase

Codebase MCP is a Model Context Protocol (MCP) server that leverages RepoMix to fetch, analyze, and summarize entire codebases. It exposes tools that let an AI agent read the full project context, including remote repositories, and save analysis outputs for future reference. The server is designed to be invoked as a CLI via npx (or a global installation of the codebase-mcp package) and can be consumed by MCP-enabled clients or agents like Cursor's Composer Agent. When started, it provides a structured set of capabilities for exploring and documenting codebases at scale.

The available tools you can access through the MCP interface include:

• getCodebase: Analyzes your current workspace or project and returns a structured representation or summary of the codebase in formats such as XML, Markdown, or plain text.
• getRemoteCodebase: Fetches and analyzes a public GitHub repository, enabling you to explore dependencies, structure, and important components of external projects without cloning locally.
• saveCodebase: Saves the generated codebase analysis to a file for later review or sharing. This is useful for snapshotting a project state at a specific point in time.

To use these tools, start the MCP server and authenticate/authorize with your MCP client. Then you can issue commands like getCodebase to analyze your current workspace, getRemoteCodebase to inspect a GitHub repository, or saveCodebase to persist the analysis to a file. The tools are designed to be friendly to AI agents, providing concise, structured outputs that can be consumed by the agent to understand project structure, components, and notable patterns.

Prerequisites:

• Node.js (>= 14.x) and npm/yarn
• Git
• Access to the internet to fetch npm packages

Installation steps:

1. Ensure Node.js and npm are installed

node -v
npm -v

2. Install the MCP package globally using npm (recommended per README)

npm install -g codebase-mcp

3. Install RepoMix if required by the MCP (the CLI mentions this as a post-install step)

codebase-mcp install

4. Start the MCP server (stdio mode or via CLI integration)

codebase-mcp start

5. Optional: Clone the repository and build if you prefer a local install workflow

# Clone the repository
git clone https://github.com/DeDeveloper23/codebase-mcp.git

# Navigate to the project directory
cd codebase-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Install globally from the built package
npm install -g .

# Install RepoMix (required dependency)
codebase-mcp install

Notes:

• If you don’t want to install globally, you can run the MCP via npx as shown in the mcp_config section.
• Ensure network access for fetching packages and remote repositories.
• The server runs in stdio mode and is compatible with any MCP client that can communicate using the MCP protocol.

Tips and common issues:

• If getRemoteCodebase fails due to repository access, verify that the repository is public or that you have proper credentials/API access configured.
• When saving codebase analyses, ensure the destination path has write permissions and enough disk space for large codebases.
• For large codebases, consider enabling options like file summaries or selective processing to reduce output size.
• Environment variables (if used) can control default formats, timeouts, and remote fetch behaviors. If you rely on custom options, document them in your deployment environment (e.g., CODEBASE_OUTPUT_FORMAT, CODEBASE_REMOTE_TIMEOUT).
• If starting the server via npx, you don’t need a local npm installation of the package; npx will fetch and run the package on demand.