MCP Directory

How to add Octocode to Windsurf

Research code like a senior staff engineer: GitHub, local FS, and LSP intelligence wired into your AI assistant. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 864★ · stdio · oauth

Windsurf config for Octocode

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

Setup steps

  1. 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
  2. 2Paste the Octocode config below.
  3. 3Fill in placeholder secrets, then save.
  4. 4Click Refresh in the MCP panel.
  5. 5Octocode's tools become available to Cascade.

Before you start

  • Node.js (pulled in automatically by Homebrew when installing the CLI)
  • GitHub authentication for the GitHub-backed tools (run `octocode login` for the GitHub OAuth device flow)

What Octocode can do in Windsurf

githubSearchCode

Search code across GitHub repositories.

githubSearchRepositories

Search for GitHub repositories.

githubSearchPullRequests

Search and explore GitHub pull requests.

githubGetFileContent

Read file contents from a GitHub repository.

githubViewRepoStructure

View the file/directory structure of a GitHub repository.

githubCloneRepo

Clone a GitHub repository locally.

localSearchCode

Search code in your local codebase using ripgrep.

localFindFiles

Find files in your local codebase.

Security

GitHub authentication is required for the GitHub-backed tools. Auth is handled via a GitHub OAuth device flow (`octocode login`), with `--hostname` support for GitHub Enterprise. The repo ships a standalone `octocode-security-utils` package. Local tools (ripgrep search, file reading, LSP) operate on your local filesystem.

Octocode + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Octocode config there under the "mcpServers" key and restart the client.

Is Octocode safe to use with Windsurf?

GitHub authentication is required for the GitHub-backed tools. Auth is handled via a GitHub OAuth device flow (`octocode login`), with `--hostname` support for GitHub Enterprise. The repo ships a standalone `octocode-security-utils` package. Local tools (ripgrep search, file reading, LSP) operate on your local filesystem.

How do I install Octocode as an MCP server?

Run `npx octocode-cli install` for the interactive installer (handles GitHub OAuth, MCP config, and skills), or add the manual `mcpServers` block with command `npx` and args `["octocode-mcp@latest"]` to your MCP configuration file. Pass `--ide <client>` for a non-interactive install.

Which AI clients are supported?

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

Do I need GitHub authentication?

Yes, for the GitHub-backed tools. Run `octocode login` to start a GitHub OAuth device flow; use `--hostname` for GitHub Enterprise.

View repo Full Octocode page