Codebase

You run a Codebase MCP Server to securely analyze projects, read and search files, inspect metadata, and traverse dependency trees. It exposes simple MCP endpoints you can connect to from your MCP client to perform fast, context-aware codebase analysis.

How to use

Use the Codebase MCP Server with your MCP client to perform key actions such as discovering project structure, reading files with metadata, locating configuration files, and analyzing dependency trees. You can run the server locally via your preferred method (npm/npx) or via a container, then point your MCP client at the configured server to start querying the project.

How to install

Prerequisites: Node.js v18 or later. A codebase you want to analyze. An MCP client setup that can connect to an MCP server.

Option 1: Run via npx (local development) with a path to your codebase.

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

Option 2: Run Codebase MCP Server in Docker.

docker build -t mcp/codebase -f .

{
  "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"
      ]
    }
  }
}

Build and run notes

If you are building and running locally, you can also install from npm and then start the server in your development environment, or use Docker for containerized execution. Ensure your codebase path is accessible to the server process.

Install variants for different environments

VS Code integration and alternative clients can connect to the same MCP server using standard MCP configuration blocks.

Cursor, Windsurf, and Claude Desktop installation examples use the same MCP startup pattern to bring up the server.

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. Follow the project guidelines for contributing and code of conduct when submitting changes.

Available 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.