OpenGrok MCP Server

OpenGrok MCP Server

MCP server bridging OpenGrok search engine with AI for instant context across massive codebases

---

<details> <summary>📚 Table of Contents</summary>

• Overview
• How to Install
• Configuration Guide
• Prompting Examples
• Tool Reference
• VS Code Integration
• System Architecture
• Building & Testing
• Troubleshooting & Support
• License Information

</details>

---

Overview

💡 Self-Contained Architecture: The VS Code extension includes the MCP server pre-packaged. You don't need Python, external Node.js installations, or complex environment setups. Just install and go.

---

How to Install

1. From the VS Code Marketplace (Easiest)

Inside VS Code, open the Extensions view (Ctrl+Shift+X), search for "OpenGrok MCP Server", and hit Install.

2. Global NPM Package

# Run directly without installing permanently
npx opengrok-mcp-server

# Or install it globally on your system
npm install -g opengrok-mcp-server

3. Via the MCP Registry

We are officially listed in the Model Context Protocol Registry under io.github.IcyHot09/opengrok-mcp-server. Clients with registry integration can locate and install it natively.

Option 4 — 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.

<details> <summary>🛠️ Option 5 — Build from source <em>(For developers)</em></summary>

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

</details>

---

Configuration Guide

1. Provide Connection Details:

   • After installation, the Settings panel will launch.
   • Input your OpenGrok endpoint, username, and password. Hit Save Settings. (Credentials are locked in your native OS keychain).
   • The plugin verifies the connection instantly. On your first run, VS Code will ask you to Reload the Window to register the MCP tools.
   • (Need to change this later? Use the OpenGrok: Manage Configuration command or click the gear icon in the status bar).

2. Activate the MCP Source in Copilot:

   • Launch the GitHub Copilot Chat window. Ensure you're using Agent mode.
   • Click the paperclip/tools icon (🔧) in the prompt box.
   • (If an Update Tools button appears, click it).
   • Locate OpenGrok in the list, check the box, and confirm.

⚠️ Note that VS Code manages tool authorizations per workspace. If you open a different repository, you may need to re-check the OpenGrok box in Copilot.

🔌 Third-Party Client Support

While tailored for VS Code, the integrated server logic runs perfectly with other agents natively supporting the MCP protocol, including:

Claude Desktop | Cursor IDE | Windsurf | Claude Code | Google Antigravity

👉 Refer to MCP_CLIENTS.md for configuration snippets, terminal wrapper scripts, and advanced daemon setups.

---

Prompting Examples

Talk to GitHub Copilot Chat naturally about your codebase:

Find the implementati