OpenGrok MCP Server

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

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.

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

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 implementation of the render_pipeline function within the graphics engine project.

Retrieve the contents of /src/utils/math.cpp from line 450 to 520.

What is the definition of TextureManager? Please show me the header file declaration too.

Look for all places in the code where ThreadPool is instantiated or referenced.

Tool Reference

Primary Operations

🚀 Optimized Workflows (Compound Tools)

💡 These specialized tools merge multiple network requests into a single operation, reducing API chatter and cutting token usage by up to 90%.

(Note: The search functions support language filtering. Pass file_type as java, cxx, python, golang, etc.)

VS Code Integration

Palette Commands

Core Settings Profile

System Architecture

 [ AI Client ]                       [ Integration Layer ]                    [ Data Source ]
                              │                                 │
 +---------------+            │       +-------------------+     │      +----------------------+
 │ GitHub        │<──(stdio)──┼──────>│ OpenGrok MCP      │<────┼─────>│ OpenGrok REST API &  │
 │ Copilot Chat  │            │       │ Server (Node.js)  │HTTP │      │ Web Interface        │
 +---------------+            │       +-------------------+     │      +----------------------+
      │    ▲                           │          │
      │    │ (Configures & Hosts)      │    (Context Optimization)
      ▼    │                           │          │
 +---------------+                     │   o Context Fetch      │      +----------------------+
 │ VS Code       │                     │   o Multi-Search       │      │ Local File System    │
 │ Extension     │                     │   o Auto-Truncate      │<─────┤ (compile_commands) │
 +---------------+                     │                        │      +----------------------+

Building & Testing

# Initializing
npm install

# Code Quality & Tests
npm run lint      # Strict TypeScript & ESLint validation
npm test          # Execute the Vitest test suite

# Packaging
npm run compile   # Generate the esbuild artifact
npm run vsix      # Create the downloadable extension file

We leverage GitHub Actions for automated CD. Tagging a commit (e.g., v1.2.3) automatically triggers the build matrix and attaches artifacts to a new GitHub Release.

For deep-dives into the architecture or PR guidelines, please read CONTRIBUTING.md.

Troubleshooting & Support

The MCP tools are missing in Copilot Chat

• Click the paperclip (🔧) icon to "Update Tools"
• Run Developer: Reload Window

"Connection failed" errors

• Double-check your OPENGROK_BASE_URL
• Make sure you aren't blocked by corporate VPNs/proxies

401 Unauthorized / Authentication failing

• Run the OpenGrok: Configure Credentials command to save your username/password again

Self-Signed SSL Certificates

• Turn off strict validation by setting opengrok-mcp.verifySsl to false

Slow queries or timeouts

• Limit the scope using the file_type argument or targeting a specific project
• OpenGrok might be indexing; run opengrok_index_health

Need verbose logs?

• Set the environment variable OPENGROK_LOG_LEVEL=debug to get extensive stdout trace data

OpenGrok Version Compatibility

License Information

This system is distributed under the PolyForm Noncommercial License 1.0.0.

• ✅ Permitted: Personal use, hobby projects, academic research, education
• ❌ Prohibited: Any commercial, business, enterprise, or paid utilization

Commercial Licensing: To use this extension in an enterprise context (internal tooling, CI pipelines, business infrastructure), a commercial license is strictly required. Reach out to [email protected] for enterprise tier pricing.

Read LICENSE-COMMERCIAL.md for full terms.