Codebase MCP Server

<p align="center"> <h1 align="center">Codebase MCP Server</h1> <p align="center">Model Context Protocol server for secure and efficient Codebase analysis</p> </p>

<p align="center"> <a href="https://github.com/yourusername/codebase-mcp-server/blob/main/LICENSE"> <img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"> </a> <a href="https://www.npmjs.com/package/codebase-mcp-server"> <img src="https://img.shields.io/npm/v/codebase-mcp-server" alt="npm version"> </a> </p>

<p align="center"> <a href="#-key-features">Key Features</a> • <a href="#-supported-languages">Supported Languages</a> • <a href="#%EF%B8%8F-tools">Tools</a> • <a href="#-quickstart">QuickStart</a> • <a href="#-build">Build</a> • <a href="#-contributing">Contributing</a>

</p>

🌟 Key Features

• Secure Access: Restricts file operations to predefined root directory.
• Efficient File Management: Provides tools for reading and searching files.
• Detailed Metadata: Retrieves comprehensive file metadata including size, creation time, last modified time, permissions, and type.
• Dependency Analysis: Traverses and analyzes dependency trees within projects.

📋 Supported Languages

• JavaScript/TypeScript
• CSS / CSS Preprocessors

🛠️ Tools

• get-project-basics: Retrieves essential project information including package.json details, directory structure.
• search-config-files: Searches for configuration files within the root directory and returns their paths.
• get-dependency-tree: Traverses the dependency tree based on the given file path and root directory, and returns the traversal results.
• list-directory: Lists the contents of a specified directory, distinguishing between files and directories.
• read-file-with-metadata: Reads the content of a specified file and retrieves its metadata.

🚀 QuickStart

Prerequisites

• Node.js v18 or later
• Codebase to communicate with LLM

Installation

First, install the Codebase MCP server with your client. A typical configuration looks like this:

{
  "mcpServers": {
    "Codebase": {
      "command": "npx",
      "args": ["codebase-mcp-server@latest", "/path/to/your/codebase"]
    }
  }
}

Or, you can install the Codebase MCP server with Docker.

After cloning this repository, build the Docker image:

docker build -t mcp/codebase -f .

And then add the following to your MCP servers file:

{
  "mcpServers": {
    "Codebase": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount",
        "type=bind,src=/path/to/your/codebase/dir,dst=/projects/path/to/your/codebase/dir,ro",
        "--mount",
        "type=bind,src=/path/to/some/file.txt,dst=/projects/path/to/some/file.txt",
        "mcp/codebase",
        "/projects"
      ]
    }
  }
}

<details><summary><b>Install in VS Code</b></summary> You can install the Codebase MCP server using the VS Code CLI:

# For VS Code
code --add-mcp '{"name":"Codebase","command":"npx","args":["codebase-mcp-server@latest"]}'

After installation, the Codebase MCP server will be available for use with your GitHub Copilot agent in VS Code.

</details>

<details><summary><b>Install in Cursor</b></summary> Go to Cursor Settings -> MCP -> Add new MCP Server. Use following configuration:

{
  "mcpServers": {
    "Codebase": {
      "command": "npx",
      "args": ["codebase-mcp-server@latest"]
    }
  }
}

</details>

<details><summary><b>Install in Windsurf</b></summary>

Follow Windsuff MCP documentation. Use following configuration:

{
  "mcpServers": {
    "Codebase": {
      "command": "npx",
      "args": ["codebase-mcp-server@latest"]
    }
  }
}

</details>

<details><summary><b>Install in Claude Desktop</b></summary>

Follow the MCP install guide, use following configuration:

{
  "mcpServers": {
    "Codebase": {
      "command": "npx",
      "args": ["codebase-mcp-server@latest"]
    }
  }
}

</details>

🔧 Build

Local Development Build

# Install dependencies
npm ci

# Build TypeScript
npm run build

Docker Build

# Build Docker image
docker build -t mcp/codebase -f .

# Or with specific tag
docker build -t mcp/codebase:latest -f .

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on our Code of conduct and the process for submitting pull requests.