MCP工具

Quick start

Prerequisites: Node.js 20.12+

1. Run the Octocode CLI with npx

npx octocode --help

2. Authenticate with GitHub - optional, but unlocks private repositories and higher API rate limits:

npx octocode auth login
npx octocode status       # verify the active token source

3. Choose your interface. Same tools and Rust engine on both. (Clone is on by default in the CLI, opt-in for MCP.)

🖥️ CLI - research straight from your terminal:

npx octocode

🤖 MCP - one-click install:

• <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">
• <img src="https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code">

<details> <summary><b>Show more install options (Windsurf, Kiro, Goose, LM Studio, Claude Code)</b></summary> <br>

• <img src="https://img.shields.io/badge/VS_Code_Insiders-Install_Server-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white" alt="Install in VS Code Insiders">
• <img src="https://img.shields.io/badge/Windsurf-Install_Server-1a1a1a?style=flat-square&logoColor=white" alt="Install in Windsurf">
• <img src="https://kiro.dev/images/add-to-kiro.svg" alt="Install in Kiro">
• <img src="https://goose-docs.ai/img/extension-install-dark.svg" alt="Install in Goose">
• <img src="https://files.lmstudio.ai/deeplink/mcp-install-light.svg" alt="Install in LM Studio">

Claude Code:

claude mcp add-json octocode --scope user '{"command":"npx","type":"stdio","args":["octocode-mcp@latest"]}'

Any other client: npx octocode install

---

Example configuration

~/.octocode/.octocoderc:

{
  "github": {
    "apiUrl": "https://api.github.com"
  },
  "local": {
    "enabled": true,
    "enableClone": true
  },
  "output": {
    "format": "yaml"
  }
}

Per-project overrides and custom LSP servers live in a workspace .octocode/ folder. For the full .octocoderc schema, a ready-to-copy example, clone-cache tuning, GitHub Enterprise setup, and precedence details, see the Configuration Reference.

---

Manual configuration

Add to your MCP client config, using octocode-mcp:

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

Add a GitHub token and options under env - see Authentication and Configuration.

---

Configuration

Everything is optional; Octocode runs on sensible defaults. Settings resolve from three sources, in priority order:

environment variables  >  <octocode-home>/.octocoderc  >  built-in defaults

1. MCP / environment variables (highest): per client or per project, set in your MCP config env or your shell.
2. Global config: <octocode-home>/.octocoderc, machine-wide defaults read by both the CLI and the MCP server.
3. Built-in defaults: used when neither is set.

Octocode home (<octocode-home>) holds the global config, encrypted credentials, sessions, stats, and tmp materialization caches. On every platform it is .octocode inside the OS home directory — ~/.octocode on macOS and Linux, %USERPROFILE%\.octocode on Windows. Override it with OCTOCODE_HOME.

Set values as MCP env entries (per client; these win over .octocoderc) or globally in <octocode-home>/.octocoderc (JSON with comments). Tokens never go in .octocoderc — use env or npx octocode auth login.

Common settings

Most-used settings (both CLI and MCP unless noted):

OCTOCODE_HOME, GitHub Enterprise (GITHUB_API_URL), MCP tool allowlisting (TOOLS_TO_RUN/ENABLE_TOOLS/DISABLE_TOOLS), and network timeouts/retries: see the Configuration Reference.

Option 1: Octocode CLI (recommended)

npx octocode auth login
npx octocode status       # verify the active token source

Interactive login lets you choose Octocode browser OAuth or gh auth login. Octocode OAuth credentials are stored encrypted on disk.

Option 2: GitHub CLI (also supported)

gh auth login

Octocode reads the gh token automatically — no further config needed.

Option 3: Personal access token (also supported)

Set OCTOCODE_TOKEN, GH_TOKEN, or GITHUB_TOKEN in your shell. Required scopes: repo, read:user, read:org.

Create a token at github.com/settings/tokens.

Note: Never commit tokens to version control. Use environment variables or secure secret management.

---

Package search

Packages

packages/octocode-benchmark (private, not published) holds benchmark methodology, evals, and run artifacts - see Documentation.

---

Agent workflows

Troubleshooting

Node.js or environment issues? Run the built-in doctor command to check your environment:

npx node-doctor

Common pitfalls: - GitHub auth failures: Ensure your Personal Access Token (PAT) has the repo and read:user scopes. If using the CLI, run npx octocode auth login to refresh. - MCP connection issues: If your AI assistant (like Cursor or Windsurf) fails to connect, ensure you have run npx octocode auth login in your terminal first, or explicitly pass your OCTOCODE_TOKEN in the MCP env configuration. - Native engine errors: Octocode uses a prebuilt Rust engine. If it fails to load on Linux, ensure your system has glibc or musl compatibility. On macOS/Windows, ensure you are on a supported architecture (x64 or arm64).

---