Octocode MCP Server

Octocode: Research Driven Development for AI

Research like a Senior Staff Engineer.
In every codebase, in seconds.

Stop guessing. Octocode gives AI agents and humans one evidence-first research engine for local workspaces, GitHub repositories, pull requests, npm packages, and LSP semantic navigation.

It has two interfaces: an MCP server for AI assistants and a CLI for terminals, scripts, and CI.

octocode.ai  ·  Quickstart  ·  Interfaces  ·  Tools  ·  CLI  ·  Develop  ·  Packages  ·  Skills

Quickstart

Pick the path that matches where you want Octocode to show up.

Add Octocode to an AI Assistant

# Interactive installer for Cursor, Claude Code, Windsurf, Codex, and more.
npx octocode-cli install

# Non-interactive install for a specific client.
npx octocode-cli install --ide cursor

Then authenticate GitHub access:

npx octocode-cli login
npx octocode-cli status

If you installed the CLI globally or with Homebrew, use octocode instead of npx octocode-cli.

Use Octocode From the Terminal

# macOS / Linux
brew install bgauryy/octocode/octocode

# npm
npm install -g octocode-cli

# First useful local loop
octocode tree .
octocode search "TODO" .
octocode get README.md

For GitHub research, login once and then point commands at owner/repo:

octocode login
octocode tree facebook/react
octocode search "useState" facebook/react
octocode pr vercel/next.js#12345

Common Workflows

Two Interfaces, One Engine

Octocode is not a chat prompt or a loose wrapper around grep. It is a tool runtime with a shared core: the MCP server and the CLI call the same tool catalog, the same security layer, the same response shaping, and the same Rust-backed hot paths.

The normal research loop is:

discover shape -> search narrowly -> read exact slices -> trace semantics -> cite evidence

GitHub-backed tools require authentication. Run octocode login, or see Authentication Setup.

MCP Server

The MCP server is the interface for AI assistants. It lets an agent search, read, trace, and compare code without pasting whole repositories into context.

npx octocode-cli install

Pass --ide <client> for a non-interactive install:

octocode install --ide cursor
octocode install --ide claude-code

{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": ["octocode-mcp@latest"]
    }
  }
}

Supported install targets include Cursor, Claude Code, Claude Desktop, Windsurf, Zed, Trae, Antigravity, Kiro, Codex, Opencode, Gemini CLI, Goose, VS Code Cline, Roo, and Continue.

https://github.com/user-attachments/assets/de8d14c0-2ead-46ed-895e-09144c9b5071

CLI

The CLI is the terminal interface to the same engine. It has two layers:

1. Smart commands for common research flows. These route to local or GitHub tools automatically and avoid raw schemas.
2. Raw tool runner for exact MCP-equivalent calls with octocode tools <name> --queries '<json>'.

Install

# Homebrew (macOS / Linux)
brew install bgauryy/octocode/octocode

# npm
npm install -g octocode-cli

# or run setup without a global install
npx octocode-cli install

The Homebrew command installs the binary as octocode.

octocode --version
octocode login
octocode status

CLI Commands

Full command reference: CLI Reference.

Raw Tool Calls

octocode tools
octocode tools localSearchCode --scheme
octocode tools localSearchCode --queries '{"path":".","pattern":"TODO"}'
octocode tools ghSearchCode --queries '{"keywordsToSearch":["useState"],"owner":"facebook","repo":"react"}'

Direct CLI tool runs auto-fill id, mainResearchGoal, researchGoal, and reasoning when omitted. MCP clients should provide those research fields explicitly.

All 12 Octocode Tools

Tool behavior references:

• GitHub Tools Reference
• Local Tools Reference
• LSP Tools Reference
• Tool Behavior Guide

Security, Token Efficiency, and Rust

Octocode is built for AI-agent workflows where the expensive part is not just execution time - it is irrelevant context, secret leakage, and untrusted inputs.

Security mechanisms

• Inputs pass through schema validation and security wrappers before execution.
• Secrets are detected and redacted in tool inputs, outputs, errors, logs, and returned content.
• Local paths are canonicalized, checked against workspace/allowed roots, and rejected when they escape allowed directories or hit ignored paths.
• Local command execution is allowlisted. Tools use controlled builders for commands such as rg, find, ls, and git; arguments are not passed through a free-form shell.
• GitHub token resolution is explicit: OCTOCODE_TOKEN, GH_TOKEN, GITHUB_TOKEN, encrypted Octocode credentials, then gh auth token.
• Clone-backed workflows require local/clone enablement and materialize into managed cache locations.

Token efficiency

• standard minification removes comments and blank-line noise while preserving readable code shape.
• symbols mode returns structural outlines with line numbers so agents can map a file before reading bodies.
• Match-based and line-based reads keep the model on the exact evidence instead of whole files.
• Bulk tools paginate results and large payloads; agents can continue from page, charOffset, or response pagination fields.
• Tool responses prefer compact, structured YAML by default because it is easier for agents to scan than raw JSON.

Rust-backed hot paths

Octocode uses Rust where it changes the feel of the product, not as a vanity rewrite:

• octocode-security runs high-volume secret detection and masking through Rust's linear-time regex engine.
• @octocodeai/octocode-context-utils handles agent-readable minification, semantic signatures, UTF-8/UTF-16 offsets, ripgrep JSON parsing, diff filtering, and YAML serialization.
• octocode-lsp owns native LSP runtime pieces: language detection, server command resolution, stdio JSON-RPC, symbol anchoring, pooled clients, and semantic requests.

That combination keeps flows fast and predictable: search broadly, read narrowly, trace semantically, return compact evidence.

Develop Locally

Run these from the repository root unless a package doc says otherwise.

yarn install
yarn build
yarn test:quiet
yarn lint

Useful editing rules for this repo:

• Documentation links in docs/ and package READMEs use absolute GitHub URLs.
• MCP behavior changes usually need tests under packages/octocode-mcp/tests/ or the owning package's tests/ directory.
• Tool descriptions and schemas come from the shared tool catalog, so update the shared source instead of patching generated output.
• Generated folders such as dist/, out/, coverage/, and node_modules/ are not source.

For the full workflow, see the Development Guide.

Troubleshooting Fast

Packages

This is a yarn-workspaces monorepo. Runtime code is split so the MCP server, CLI, and extension share one tool core instead of each reimplementing research behavior. Setup/reference docs live in docs/, and AI-agent guidance lives in AGENTS.md.

Skills

Agent Skills are a lightweight, open format for extending AI agent capabilities. Skills index: skills/README.md

Research & Code Analysis

Planning & Writing

Review & Critique

Build & Output

Tooling & Setup

https://github.com/user-attachments/assets/5b630763-2dee-4c2d-b5c1-6335396723ec

Documentation

Full index: docs/README.md. All monorepo documentation lives in docs/ (no per-package docs/).

Docs map

• docs/configuration/: install, auth providers, MCP clients, env/config, troubleshooting
• docs/dev/: tool/API references, workflows, architecture, contributing, skills
• docs/specs/: design specs and RFCs

Setup

• Authentication Setup
• Configuration Reference
• Using octocode-mcp with Pi

Tool References

• GitHub Tools
• Local Tools
• LSP Tools
• Clone & Local Workflow

CLI & Skills

• CLI Reference
• Skills Guide · Skills Index

Shared Internals

• Credentials Architecture · Session Persistence

Operations

• Development Guide · Agent Guidance (AGENTS.md)

The Manifest

"Code is Truth, but Context is the Map." Read the Manifest for Research Driven Development to understand the philosophy behind Octocode.

Contributing

See the Development Guide for monorepo setup, testing, and contribution guidelines.