OpenGrok MCP Server

Search your OpenGrok code index directly from GitHub Copilot Chat

🔌 Zero Install  ·  🧠 Compound Tools  ·  🔄 Auto-Updates  ·  🔒 Secure Credentials

• Do I need anything installed?

• Installation

• Setup & Configuration

• Usage

• Available Tools

• Extension Commands

• Extension Settings

• Architecture

• Development

• License

Do I need anything installed?

💡 No. Installing the VSIX is enough. The MCP server is bundled inside the extension — no Python, no Node.js, no separate installs required.

Installation

Option 1 — VS Code Marketplace (Recommended)

Search for "OpenGrok Code Search for Copilot" in the VS Code Extensions panel (Ctrl+Shift+X) and click Install.

Option 2 — Install pre-built VSIX

1. Download the latest VSIX file from GitHub Releases.

2. Install it in VS Code:

   • Open the terminal in VS Code and run: code --install-extension opengrok-mcp-server-X.Y.Z.vsix

   • OR go to the Extensions tab → click the ··· menu → Install from VSIX… and select the file.

3. Updates are automatic — the extension checks GitHub Releases once per day and offers one-click install.

git clone https://github.com/IcyHot09/opengrok-mcp-server.git
cd opengrok-mcp-server
npm install
npm run vsix          # Creates opengrok-mcp-server-*.vsix
code --install-extension opengrok-mcp-server-*.vsix

Setup & Configuration

1. Configure Credentials:

   • Upon installing, the Configuration Manager webview opens automatically.

   • Enter your OpenGrok server URL, username, and password, then click Save Settings. (Password is saved securely in the OS keychain.)

   • A connection test runs automatically. First-time setup requires a Reload Window to enable tools.

   • (Manage configuration later via the gear icon in the Status Bar, or

2. Enable the Tools in Copilot (First Time Only):

   • Open GitHub Copilot Chat in Agent mode.

   • Click the 🔧 in the chat input box.

   • If you see Update Tools, click it first.

   • Check OpenGrok in the list and click Done.

⚠️ Tool selection is per workspace — re-enable in each new workspace as needed.

🔌 Using with Other MCP Clients

The standalone MCP server works with any MCP-compatible client:

Claude Code · Cursor · Windsurf · Claude Desktop · OpenCode · Google Antigravity

👉 See for the one-command installer, per-client config snippets, and security considerations.

Usage

In GitHub Copilot Chat, describe what you're looking for in natural language:

Use OpenGrok to search for RenderPipeline in the my-project project

Ask OpenGrok to show me the file at /path/to/file.cpp lines 100-200

Have OpenGrok find the definition of CacheManager and show me the header too

Search for all references to TaskScheduler across the codebase

Available Tools

Core Tools

🚀 Compound Tools — Use These First

💡 These collapse common multi-step patterns into a single call, saving ~75–92% of tokens.

file_type — search_code, batch_search, search_and_read, and get_symbol_context accept an optional file_type to restrict results by language: cxx, c, java, python, javascript, typescript, csharp, golang, ruby, perl, sql, xml, yaml, shell, makefile.

Extension Commands

Extension Settings

Local Source Layer

The local layer is zero-config — if your workspace contains compile_commands.json, get_compile_info is enabled automatically.

Architecture

┌─────────────────┐     ┌──────────────────────────────┐     ┌──────────────┐
│  GitHub Copilot │────▶│  opengrok-mcp-server (MCP)   │────▶│  OpenGrok    │
│  Chat           │stdio│                              │HTTP │  Server      │
└─────────────────┘     │  Compound tools:             │     └──────────────┘
        ▲               │  · get_symbol_context        │
        │               │  · search_and_read           │     ┌──────────────┐
        │ configures    │  · batch_search              │────▶│  Local FS    │
        │ + bundles     │                              │     │  (optional)  │
┌───────┴─────────┐     │  Response cap: 16 KB         │     └──────────────┘
│  VS Code        │     │  MCP instructions block      │
│  Extension      │     └──────────────────────────────┘
└─────────────────┘

The MCP server is compiled and bundled inside the VSIX as out/server/main.js. VS Code provides its own Node.js runtime — no separate installation needed.

Development

npm install
npm test          # Run unit tests (Vitest)
npm run lint      # TypeScript type-check + ESLint
npm run compile   # esbuild bundle
npm run vsix      # Package as .vsix

Releases are automated via GitHub Actions — push a version tag (vX.Y.Z) and the workflow builds, tests, and publishes to GitHub Releases.

See CONTRIBUTING.md for the full development guide.

License

This project is licensed under the PolyForm Noncommercial License 1.0.0.

This project is free for personal and non-commercial use. For enterprise or commercial licensing, please contact me at rudroy09@gmail.com.