basemind MCP
One MCP server gives agents a code map across over 300 languages, git history, shared memory and document search with OCR.
- 117 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The `shell` and `web` domains start terminal sessions and use the network on the agent's command.
- The index, memory and document text stay on disk, and `basemind init` appends a rules block to project files.
Install
- Works in
Manual install
/plugin marketplace add Goldziher/basemind
/plugin install basemind@basemindThe recommended path: the plugin downloads the program on first use.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The `shell` and `web` domains start terminal sessions and use the network on the agent's command.
- The index, memory and document text stay on disk, and `basemind init` appends a rules block to project files.
This is third-party code. Review the repository files before installing.
What it does
basemind indexes a repository and answers an agent with file paths, line numbers and signatures instead of whole files. The `code` tool shows a file outline and finds definitions, call sites and interface implementations. `graph` builds a call graph and an architecture map, and `git` tells who changed a function or a line and when. The server has nine domains: `code`, `graph`, `git`, `memory`, `web`, `agents`, `shell`, `admin` and `workspace`. Among them, `memory` keeps shared repository memory and searches PDFs, Office files, HTML and images with OCR, `agents` links several agents through message threads, `shell` runs background terminal sessions, and `web` collects pages. The index lives in a global cache on the user's machine.
Who it is for. Developers who run agents over large repositories and want to spend fewer tokens on reading files.
Good fit when
- An agent in Claude Code burns its context on `grep` and file reads in a monorepo.
- Before a refactor you need every call site of a function and every implementation of an interface.
- You want to know who last changed a line and when a function body changed.
- Several agents work in one repository and exchange messages through threads.
- Project PDFs and documents are searched by meaning together with the code.
Not a fit when
- The repository is small and direct file reads are enough for the agent.
- The computer cannot download the document and search models on first run.
- The agent should not get background terminal sessions and web page collection.
Example request
Show the outline of `src/server.ts`, find every call site of `processFile` and tell me who last changed that function.MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
BASEMIND_BIN- Path to a local build that the plugin launches instead of the downloaded release.
Limitations
The plugin downloads the basemind program on first use, and full-feature builds fetch the document and search models on first run. `cargo install basemind --locked` builds only the code map and git tools, while `basemind serve` needs `--features comms`. Manual MCP setup and Pi need the program installed separately. The `shell` and `web` domains widen what an agent can do, so enable auto-approval only for safe reads. `basemind init` appends a rules block to `CLAUDE.local.md` or another project file.
How to disable. Remove the plugin through the agent's plugin manager or the basemind entry from the MCP configuration. Delete the rules block from `basemind init` by hand: it sits between the `BEGIN basemind` and `END basemind` markers. The index lives in `~/.local/share/basemind/` on Linux.
FAQ
How do I connect basemind to Claude Code?
In a session, run `/plugin marketplace add Goldziher/basemind`, then `/plugin install basemind@basemind`. After a restart, run `/bm-statusline` once to enable the statusline. Without the plugin, register the server with `claude mcp add basemind -- basemind serve`.
How does the plugin differ from manual MCP setup?
The plugin downloads the matching program version itself. With manual setup you install the program through Homebrew, npm, pip or cargo and use `basemind serve` as the launch command.
What does `basemind init` do?
It creates `basemind.toml`, asks which capabilities to enable and adds a rules block that prefers basemind over grep. By default the block goes to `CLAUDE.local.md`, which git ignores. `--print` shows the changes without writing.
Does basemind work in Cursor and Codex?
Yes. In Cursor, add an `mcpServers` block to `.cursor/mcp.json`; in Codex, run `codex mcp add basemind -- basemind serve`. The README also covers Windsurf, Gemini CLI, Copilot CLI, Cline and OpenCode.
Where is the index stored?
In a single global cache on the machine. On Linux that is `~/.local/share/basemind/`. It is shared by all working copies of a repository on that computer.
Discussion
No questions or reviews yet.
Related
MCP serversAn MCP server that builds a code graph of functions, classes, calls and routes and answers the agent's structural queries locally
A local code graph with version history: an MCP server that tells the agent who calls a function and what an edit breaks
GraphMind
graphmind
Local MCP server that builds a code graph and remembers project decisions, so the agent stops re-reading the repo every session
An MCP server that indexes code with tree-sitter and returns individual functions and classes to the agent instead of whole files
A persistent-memory MCP server for coding agents: a graph of a project's concepts, architecture and decisions that survives across sessions
A local codebase index for agents: hybrid search, dependency graphs and change impact analysis
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| basemind (this card) | no | not required | 117 | |
| codebase-memory-mcp | no | not required | 48,228 | codebase-memory-mcp builds a code graph and answers structural queries; basemind adds git history, documents with OCR, shared memory and agent messaging |
| Serena | no | not required | 31,148 | Serena gives the agent IDE features through LSP or JetBrains; basemind indexes code with tree-sitter and needs no language servers |
README in short
The repository holds a plugin for eleven agent profiles with ten public skills and six commands. A terminal adapter for OpenCode and a Pi extension are separate. The program is written in Rust and ships through Homebrew, npm, pip, cargo and binary releases.