open-codebase-index MCP
A local semantic code index: the agent searches by meaning, then follows hits into definitions, callers and dependency paths
- 230 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Reads the project sources and builds an index on disk; code chunks go to an external embeddings provider if OpenAI or Google is chosen
- Watches files and rebuilds the index on changes, and the Claude Code plugin runs an MCP server through npx
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/open-codebase-indexDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Reads the project sources and builds an index on disk; code chunks go to an external embeddings provider if OpenAI or Google is chosen
- Watches files and rebuilds the index on changes, and the Claude Code plugin runs an MCP server through npx
This is third-party code. Review the repository files before installing.
What it does
open-codebase-index builds a local index of a repository and hands it to the agent as a set of tools. Files are parsed with tree-sitter, code chunks get embeddings, and search joins a vector approach with BM25 keyword matching. Metadata is stored in SQLite and vectors in usearch, all next to the project: `.opencode/` for OpenCode, `.claude/` for Claude Code, `.codebase-index/` for Codex and Pi. The tools are built to save tokens. `codebase_context` assembles a compact evidence pack for a question, `codebase_peek` shows files and symbols without bodies, `codebase_search` returns full code, and `implementation_lookup` finds a definition. `call_graph` and `call_graph_path` show calls and paths between symbols, `find_similar` looks for analogues, and `pr_impact` estimates the impact of a branch or current edits. The index is incremental and branch-aware. Embeddings come from Ollama, OpenAI, Google or a compatible endpoint, and in `auto` mode providers are tried in that order. Hosts connect in different ways: a native OpenCode plugin, a marketplace plugin for Claude Code and Codex with the `codebase-search` skill, a package for Pi, and the `open-codebase-index-mcp` server for Cursor, Windsurf and others. A terminal command `ocbi` is also included.
Who it is for. Developers of large repositories where the agent burns tokens reading extra files, and anyone who wants meaning-based code search without shipping sources to a cloud index.
Good fit when
- The agent does not know a function name and is looking for where auth state is validated before an API request
- You need every caller of a method and the path from one symbol to another through `call_graph_path`
- Before an edit you want the impact of a branch or uncommitted changes from `pr_impact`
- The project is large and a compact `codebase_context` replaces a dozen files the agent would open
- You work in OpenCode, Claude Code, Codex, Pi or Cursor and want one index for all of them
Not a fit when
- The repository is small and the agent is fine with plain text search
- You have neither a local Ollama nor an embeddings provider key: the index cannot be built without them
- You need exact string search: for literals the docs advise plain reads and `grep`
Example request
Index this repository and find where auth state is validated before an API request, then show the calling functionsMCP
- Transport
- stdio
- Authentication
- not required
Limitations
- The first index needs embeddings from Ollama, OpenAI, Google or a compatible endpoint. With an external provider, code chunks go to that provider.
- Node.js 22.22 or newer is required, and 24 LTS is recommended.
- The old `opencode-codebase-index` and `opencode-codebase-index-mcp` packages remain aliases, while new installs use `open-codebase-index`.
- Test references in `codebase_edit_context` come from source and do not prove runtime coverage.
How to disable. For OpenCode remove `open-codebase-index` from the plugin list in `opencode.json`. In Claude Code uninstall the plugin with `/plugin`, in other clients drop the MCP server entry. The index goes away with the `.opencode/`, `.claude/index/` or `.codebase-index/` folders in the project.
FAQ
How do I connect open-codebase-index to Claude Code?
In Claude Code add the marketplace with `/plugin marketplace add Helweg/open-codebase-index` and install `/plugin install codebase-index@helweg-plugins`. The plugin brings the MCP settings and the `codebase-search` skill. Then open a new session in the target folder.
How is open-codebase-index different from claude-context?
claude-context keeps its index in a vector database and returns the needed fragments. open-codebase-index stores everything locally in SQLite and usearch, is branch-aware and adds a call graph, symbol path search and branch impact.
Which search tool should I use?
For a first look at unfamiliar code use `codebase_context` with `tokenBudget: 600` and `limit: 5`, for a file list `codebase_peek`, for full code `codebase_search` and for an exact definition `implementation_lookup`.
Does it need the internet?
Not for storage, since the index is local. The internet is needed if embeddings come from OpenAI or Google. With Ollama and a model such as `nomic-embed-text` everything stays on the machine.
Which languages does the index parse?
Native parsing covers TypeScript, JavaScript, Python, Rust, Swift, Go, Kotlin, Java, C#, Ruby, C/C++, PHP, Bash, Zig and more. Other formats are indexed as plain text.
Discussion
No questions or reviews yet.
Related
MCP serversA local codebase index for agents: hybrid search, dependency graphs and change impact analysis
A Rust MCP server and CLI with a call graph and hybrid semantic code search for Claude Code and Codex
An MCP server that indexes a local repository with tree-sitter and gives the agent code search, file lookup and a structure summary of a file
A local MCP server that indexes your code so the agent pulls the functions it needs instead of rereading whole files
A local MCP server and CLI for agents: semantic code search, call graphs and change-impact analysis
An MCP server that turns a large codebase into a semantic feature graph for precise navigation and meaning-based search
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| open-codebase-index (this card) | no | not required | 230 | |
| Claude Context | yes | API key | 12,673 | keeps the project index in a vector database and returns the needed fragments |
| Serena | no | not required | 31,148 | gives the agent IDE features: symbol search, editing and renaming |
README in short
The README starts with a local semantic index and installing the package with the `ocbi` command. It then lists strengths (hybrid search, token savings, incremental indexing, parsing of dozens of languages), a quick start for OpenCode and a host table. It continues with a recommended workflow, how to choose a search tool, the indexing diagram, embedding providers and a config example.