home / mcp / codebase context mcp server

Codebase Context MCP Server

Provides codebase indexing, symbol search, outline, and project summary across multiple languages via MCP stdio transport.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "jhackman2019-codebase-context-mcp": {
      "command": "node",
      "args": [
        "/path/to/codebase-context-mcp/dist/index.js"
      ]
    }
  }
}

You have a cross‑platform MCP server that indexes codebases, builds an in-memory JSON index, and provides fast search and structure queries across languages. It runs without native bindings, so it works on ARM64 devices like Raspberry Pi and Apple Silicon, making code search and navigation reliable on any host.

How to use

To use this MCP server, connect a client that speaks the MCP stdio transport. You can index a project, search for symbols or code, retrieve a file outline, and generate a project summary. The server keeps an incremental index so only changed files are processed, and stores the index as a JSON file in your home directory.

Typical workflows include indexing a codebase, then running full-text or symbol-based searches across the indexed files. Use the outline endpoint to inspect the structure of individual files, and request a high-level project summary to understand language distribution and directory layout.

How to install

Prerequisites you need before installing: node and npm on your system, a Git client if you plan to clone the repository, and a compatible shell for running commands.

1) Install dependencies and build the MCP server if you are using a local clone:

```bash
git clone https://github.com/Jhackman2019/codebase-context-mcp.git
cd codebase-context-mcp
npm install
npm run build
```

2) Start the MCP server locally using the final runtime command shown in the build guidance:

```bash
node /path/to/codebase-context-mcp/dist/index.js
```

3) Alternatively, add the server to your MCP client using the provided integration flow:

```bash
claude mcp add codebase-context -s user -- npx codebase-context-mcp
```

4) If you prefer a persistent setup via MCP settings, configure the server entry as shown in the JSON example below.

Configuration and startup details

You can configure the MCP server in your client settings to point at the local runtime. The following example shows how to wire up the server in settings, using a local stdio configuration.

{
  "mcpServers": {
    "codebase-context": {
      "command": "node",
      "args": ["/path/to/codebase-context-mcp/dist/index.js"]
    }
  }
}

Available tools

index_codebase

Parse a directory into symbols and chunks, caching the result as JSON to enable fast repeated searches.

search_symbols

Find functions, classes, or types by name or pattern using the indexed symbol data.

search_code

Perform BM25 full-text search across indexed files to locate relevant code snippets.

get_file_outline

Retrieve the structural outline of a file, including functions, classes, imports, and exports with line numbers.

get_project_summary

Provide an overview of the project’s tech stack, language distribution, and directory structure.