# Octocode

> Octocode is an open-source MCP server for developer tools. Local code search and symbol graph for AI assistants, built in Rust. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, macOS, Linux, Windows
- **Website:** https://octocode.muvon.io
- **Repository:** https://github.com/muvon/octocode
- **MCP Registry name:** io.github.Muvon/octocode
- **Categories:** developer tools
- **Listing updated:** 2026-11-14

## About

Two layers sit behind the MCP tools. The always-on layer is a tree-sitter graph of files, symbols and their contains, imports, calls, extends and implements links, built from the current source with no index to go stale. The optional layer adds embedding-based search over an index you create with octocode index, and language-server tools when you start it with --with-lsp.

Structural search matches code by syntax shape, such as every .unwrap() call, which grep cannot express. Search can take several queries at once, filter by language, search documentation, or search Git history by meaning with a commits mode.

Defaults are local: FastEmbed models on CPU, no API key, and .gitignore respected; cloud embedding providers are opt-in. The project publishes a benchmark of 127 annotated queries against its own source, including a finding that a generic reranker hurt results. The website also links to Octomind cloud plans, which are separate from the CLI.

## Features

- **Live symbol graph:** Tree-sitter extracts files, symbols and relationships directly from current source.
- **Structural search:** Finds code by AST pattern regardless of formatting or names.
- **Semantic and hybrid search:** Combines vector and keyword search with configurable reranking.
- **LSP navigation:** With --with-lsp, adds go-to-definition, references and hover from a language server.
- **Commit search:** Searches Git history by meaning to find the change that introduced a pattern.
- **Local by default:** Uses local embedding and reranking models with no API key.

## Good for

- Onboard to an unfamiliar codebase by tracing a flow across files
- List every caller and importer before refactoring a function
- Find all instances of a syntax pattern across a repo
- Give Claude Code or Cursor repository-wide context
- Locate which commit introduced a behaviour

## Install

### Claude Code (Terminal)

```sh
claude mcp add octocode -- npx -y @muvon/octocode
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": [
        "-y",
        "@muvon/octocode"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": [
        "-y",
        "@muvon/octocode"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "octocode": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@muvon/octocode"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": [
        "-y",
        "@muvon/octocode"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": [
        "-y",
        "@muvon/octocode"
      ]
    }
  }
}
```

## Tools

- `graphrag`: Graph lookup, relationship traversal and path finding.
- `structural_search`: AST pattern matching across the tree.
- `lsp_goto_definition`: Language-server go-to-definition.
- `lsp_find_references`: Language-server find references.
- `lsp_hover`: Language-server hover information.

## FAQ

### Does it need an API key?

No. Default embedding and reranking run locally with FastEmbed; remote providers are optional.

### Which clients does it support?

Claude Code, Codex CLI, Claude Desktop, Cursor and Windsurf are documented.

### Do I have to index first?

Only for semantic search. Structural search, signatures and the dependency graph read current source without an index.

### How do I install it?

Use the install script, brew install muvon/tap/octocode, cargo install octocode, or the npm package @muvon/octocode.

### Is Octocode free?

Yes. Octocode is open source, so you can use and self-host it for free.

### How do I add Octocode to Claude Code?

Run this command in your terminal: claude mcp add octocode -- npx -y @muvon/octocode

### What are the best alternatives to Octocode?

The closest alternatives to Octocode are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.
- [Claude Code Ultimate Guide](https://ai-powered.com/mcp/claude-code-ultimate-guide): Claude Code Ultimate Guide is an open-source MCP server for ai models and llm tooling.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.

---
Source: https://ai-powered.com/mcp/octocode
