OPENGROK_API_VERSION — OpenGrok REST API version. Use v2 for call graph features (requires OpenGrok 1.12+).
HTTP_PROXY — HTTP/HTTPS proxy URL for all OpenGrok API requests (e.g. http://proxy.company.com:8080). Also set as HTTPS_PROXY.
OPENGROK_RESPONSE_FORMAT_OVERRIDE — Force a specific response format for all tools. Leave unset for per-tool auto-selection (recommended).
OPENGROK_MEMORY_BANK_DIR — Directory where the AI stores investigation notes (active-task.md, investigation-log.md). Defaults to ~/.config/opengrok-mcp/memory-bank/ or workspace-relative when set by the VS Code extension.
OPENGROK_LOCAL_COMPILE_DB_PATHS — Comma-separated paths to compile_commands.json for C/C++ compiler flag and include-path extraction. Leave unset for automatic workspace discovery.
OPENGROK_ENABLE_ELICITATION — Interactive AI Prompts — the AI pauses to ask questions during investigations (project selection, file disambiguation). Requires Claude Code v2.1.76+ or a client that supports MCP Elicitation.
OPENGROK_ENABLE_SAMPLING — AI Sampling — allow the server to request LLM completions for error explanations and summaries. Off by default to avoid consuming premium requests (e.g. GitHub Copilot).
OPENGROK_SAMPLING_MODEL — Model preference for MCP Sampling (used for error explanation and query reformulation).
OPENGROK_ENABLE_FILES_API — Files API Cache — avoids re-uploading unchanged investigation notes. Requires Files API support in the MCP client.
OPENGROK_ENABLE_OBSERVATION_MASKER — Observation Masker — prepend compact history summaries to opengrok_execute results after N turns. Disabled by default; has no benefit for clients that retain full context (Claude Code, Cursor).
OPENGROK_OBSERVATION_MASKER_TURNS — Number of most-recent opengrok_execute results to keep as full text before masking older ones. Default: 10.
OPENGROK_SAMPLING_MAX_TOKENS — Maximum tokens for AI sampling responses (error explanation, query reformulation). Range: 64–4096.
OPENGROK_AUDIT_LOG_FILE — Path to write structured audit events (CSV/JSON). Appends tool invocations, elicitation events, and errors. Leave unset to disable.
OPENGROK_RATELIMIT_RPM — Maximum requests per minute to the OpenGrok server. Default: 60.
OPENGROK_PER_TOOL_RATELIMIT — Per-tool rate limits in requests per minute, as comma-separated tool:rpm pairs (e.g. opengrok_execute:15,opengrok_search_code:30). Overrides OPENGROK_RATELIMIT_RPM for specific tools.
OPENGROK_TIMEOUT — HTTP request timeout in seconds for OpenGrok API calls. Increase for slow servers. Default: 30.
OPENGROK_DEFAULT_MAX_RESULTS — Default maximum number of results returned per search query. Default: 25.
OPENGROK_PASSWORD_FILE — Path to a file containing the OpenGrok password (file-mounted secret for containers). Takes precedence over the OS keychain when OPENGROK_PASSWORD is unset.
OPENGROK_MAX_RESPONSE_BYTES — Hard cap on response payload size in bytes. Overrides the context-budget default. Non-positive values are ignored.
OPENGROK_SEARCH_AND_READ_CAP — Cap for the search_and_read compound tool in bytes. Overrides the context-budget default (2–8 KB depending on tier). Non-positive values are ignored.
OPENGROK_STRICT_SSRF — When true, reject OPENGROK_BASE_URL values pointing at private/loopback IPs at startup. Default: false (warn only; per-request guards still apply).
OPENGROK_JWT_ISSUER — Expected JWT issuer (iss claim) for HTTP transport OAuth. When set, JWTs from other issuers are rejected.
Code intelligence for any OpenGrok-indexed codebase — search, read, blame, symbol navigation, diffs, commit history, call graphs, dependency maps, and guided investigation. Optimized for token efficiency through Code Mode and AST-aware code reads.
MCP server bridging OpenGrok search engine with AI for instant context across massive codebases.
Auf PlugMCP ausführen
Host a copy with our keys and logs.
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
Install OpenGrok MCP from the VS Code Marketplace, or search "OpenGrok" in the Extensions panel. The configuration panel opens on first launch — enter your OpenGrok endpoint, username, and password, then click Save Settings and reload when prompted.
The extension provides a visual configuration UI and manages the MCP server process automatically. No Python, external Node.js install, or manual environment setup required.
opengrok-mcp status # health check: validates connectivity and detects installed MCP clients
opengrok-mcp setup --test # test the stored connection without the wizard
opengrok-mcp setup --set contextBudget=generous # update one stored setting non-interactively
opengrok-mcp export-audit --format json --output audit.jsonl # export the audit log
opengrok-mcp version # print version and exit
opengrok-mcp help # show all commands
Works with any MCP-compatible client (CLI or IDE). See MCP_CLIENTS.md for config format and troubleshooting.
Credentials are stored in the OS keychain (macOS Keychain, Windows Credential Manager, Linux libsecret) with an AES-256-GCM encrypted file fallback for headless environments.
[!TIP]
Automatic Updates — The extension checks GitHub for new releases once per 24 hours and notifies you when one is available. Use OpenGrok: Check for Updates to check on demand.
The Problem
Engineers working in large codebases face a specific gap when using AI coding assistants. The model's context window contains the file currently open, the conversation, and whatever has been manually shared — but a production codebase has structure, history, and cross-module relationships that exist entirely outside that window.
A symbol defined in one module and called from seventy others. A function whose behavior only becomes clear from the three commits that shaped it. An include chain stretching across a dozen directories. A call graph showing which components depend on a service before it gets refactored.
Without access to the code index, the model fills these gaps by guessing: it fabricates file paths, invents function signatures, misattributes changes to authors. The model is not wrong because it is unintelligent — it is wrong because it is isolated.
OpenGrok already solves this for human engineers. It indexes source in dozens of programming languages, maintains a full-text index across committed history, and exposes definition lookups, reference graphs, blame, directory traversal, and file history through a REST API. The problem was that AI tools had no way to reach it.
How It Works
┌──────────────────────────────────────────────────────┐
│ AI Client (Claude, Copilot, Cursor, Codex …) │
└─────────────────────┬────────────────────────────────┘
│ MCP (stdio or HTTP)
┌─────────────────────▼────────────────────────────────┐
│ OpenGrok MCP Server (Node.js) │
│ opengrok_api ──── full API spec, once per session │
│ opengrok_execute ─ run JavaScript in sandbox │
│ │
│ OpenGrok client ── search · symbols · blame · diffs │
└─────────────────────┬────────────────────────────────┘
│ HTTP (REST + web fallback)
┌─────────────────────▼────────────────────────────────┐
│ OpenGrok │
│ search · symbols · call graphs · index health │
└──────────────────────────────────────────────────────┘
The server exposes two primary tools. opengrok_api delivers the full API specification at session start. Every subsequent operation goes through opengrok_execute: the AI writes a JavaScript program using the env.opengrok.* object — search, getFileContent, getFileAnnotate, getFileHistory, browseDir, getFileSymbols — and submits it as a single execution.
Intermediate results stay inside the sandbox; only the final return value crosses back to the context window. A complete investigation — find the symbol, read the definition, check who changed it, trace the callers — is one script, not a sequence of round-trips with results flowing through the context between each. Token savings of 80–95% are typical for complex investigations.
All env.opengrok.* calls appear synchronous inside sandbox code — the QuickJS WASM VM bridges async HTTP calls transparently over a SharedArrayBuffer + Atomics channel (8 MB data region, 62 s per-call timeout, 62 s hard execution cap), while keeping the Node.js event loop free.
Memory bank — two files persist across turns and session restarts: active-task.md (4 KB) for current investigation state and investigation-log.md (32 KB) for append-only findings. Inside the sandbox: env.opengrok.readMemory() / env.opengrok.writeMemory(). See the Memory Bank reference below.
Reference
31 tools total: 2–5 in Code Mode (opengrok_api + opengrok_execute, plus 3 memory tools when OPENGROK_ENABLE_MEMORY_TOOLS=true) and 26 in standard mode (OPENGROK_CODE_MODE=false).
Primary Tools
Tool
Purpose
opengrok_search_code
Full-text, definition, reference, path, and history search. Supports file_type filtering and cursor pagination.
opengrok_find_file
Locate files by name or directory pattern. Supports cursor pagination.
opengrok_get_file_content
Read source code. Use start_line / end_line for large files.
opengrok_get_file_history
Commit history for a file. Supports cursor pagination.
Blame with line range (line_start / line_end) and optional diff
opengrok_call_graph
Call chain tracing via OpenGrok API v2 (requires OPENGROK_API_VERSION=v2; refs-based fallback on v1)
opengrok_get_file_diff
Unified diff between two revisions with context lines
opengrok_get_compile_info
C/C++ compiler flags and include paths from local compile_commands.json
opengrok_get_all_matches
All matching lines in a file when search shows truncated hits
opengrok_get_file_history_with_files
Commit history with co-changed file lists via RSS feed
opengrok_get_download_url
Direct download URL for a file (no HTTP call)
opengrok_list_groups
Project groups (empty when admin auth required)
opengrok_get_suggest_popularity
Popular suggestions for a project field (empty when admin auth required)
opengrok_get_project_repositories
Repositories for a project (empty when admin auth required)
(Note: search tools support language filtering. Pass file_type using the canonical analyzer name — cxx for C++, golang for Go, sh for shell, javascript for JS. Aliases accepted: cpp/c++→cxx, go→golang, bash/shell→sh, js→javascript, ts→typescript, cs→csharp, py→python, rb→ruby, rs→rust.)
defs/refs/symbol fallback notes — defs, refs, and symbol searches require a project scope (pass projects or set OPENGROK_DEFAULT_PROJECT); without one they may return too many cross-project hits. On instances where the REST endpoint returns an error or empty results for these types, the client automatically falls back to web-UI parsing so the LLM still gets answers. opengrok_call_graph needs API v2 and degrades to a refs-based view on v1.
Set OPENGROK_CODE_MODE=true (the default). Call opengrok_api once at session start to receive the full API spec. All subsequent operations go through opengrok_execute.
All sandbox API calls are synchronous — flat globals (search(...)), no await. The env.opengrok.* object form (env.opengrok.search(...)) is equivalent.
All matching lines in a file when search results show truncated hits. Also used automatically when search() is given a file: filter (no pagination)
search() uses canonical file type names only (e.g. cxx, golang, sh) — see the alias list above. Pass expandFunction: true to expand matching results to their enclosing function body (adds host-side reads, up to 3 files per call).
Cursor pagination — Methods that return a cursor field (search, findFile, browseDir, getFileSymbols, getFileHistory, getFileDiff) support pagination. Pass the cursor back as opts.cursor on the next call to fetch the next page. If a cursor has expired (session restarted or too much time elapsed), the response contains { _cursorExpired: true } — restart pagination from the beginning.
Read & Navigate
Method
Returns
env.opengrok.getFileContent(project, path, opts?)
{ project, path, content, lineCount, sizeBytes, startLine }. Range reads expand to the enclosing function by default; pass {expandFunction: false} to keep the exact range
Call chain tracing. direction: 'callers'|'callees'|'both'. ASYNC — may return {status:'computing'} on first call; retry the same call to collect the cached result
env.opengrok.getSymbolContext(symbol, opts?)
Definition + refs + headers combined. Definition expands to the full function body via tree-sitter
env.opengrok.dependencyMap(project, path, opts?)
Dependency graph: uses (imports) + used_by (references). ASYNC with fast-path — may return {status:'computing'}; retry to get the cached graph. direction: 'uses'|'used_by'|'both'
env.opengrok.getCompileInfo(path)
C/C++ compiler flags and include paths, or null when no local compile DB is configured
traceCallChain callers come from refs search; callees come from tree-sitter AST analysis for supported languages (C/C++, Java, Go, Python, JS/TS, Rust, and more). Both long-running methods fan out over a background client — a rate-limit-free sibling connection with a short per-operation budget — so deep traversals don't consume the foreground rate-limit quota.
When search() returns zero results and sampling is enabled, _suggestions: string[] is automatically injected into the result — check it before calling sample() explicitly.
Tree-sitter intelligence — range reads and expandFunction expand matches to enclosing function bodies using tree-sitter AST analysis (WASM grammars, no host toolchain needed). Per-tier line budgets apply: minimal 200 lines, standard 400 lines, generous 600 lines. Override the grammar directory with OPENGROK_GRAMMAR_DIR; contribute new grammars via npm run copy-grammars (see CONTRIBUTING.md).
fitToBuffer truncation — sandbox results that exceed the 8 MB bridge buffer are trimmed by fitToBuffer(), which keeps complete result elements rather than truncating mid-JSON. Trimmed results carry _truncated: true — narrow the query or page with cursor when you see it.
Elicitation (OPENGROK_ENABLE_ELICITATION=false to disable, default: true)
When enabled, opengrok_api prompts the user to select a working project at session start if no OPENGROK_DEFAULT_PROJECT is configured and more than one project exists. Sandbox code can also call env.opengrok.elicit() to ask the user to choose between multiple matches during execution. Requires a client that supports MCP Elicitation — Claude Code v2.1.76+ supports this. Degrades gracefully to { action: "cancel" } on other clients.
Delegates LLM calls back to the client via MCP Sampling, using the client's model subscription without separate API keys. Triggers automatically in three places: sandbox error explanation, large dependency graph summarization (>10 nodes), and zero-result query reformulation (_suggestions injection). VS Code Copilot supports sampling; other clients vary. The server degrades gracefully when sampling is unavailable.
[!WARNING]
Sampling triggers are automatic — not on-demand. A single investigation session can generate many sampling calls across sandbox errors, zero-result searches, and large dependency graphs. Some clients consume premium requests per call after the first confirmation prompt. Enable with this in mind.
Code Mode includes 2 tools by default (api + execute; 5 with OPENGROK_ENABLE_MEMORY_TOOLS=true). Two files persist across turns and session restarts:
Tool
Purpose
opengrok_memory_status
Status, size, and 3-line preview of both memory files
opengrok_read_memory
Read active-task.md or investigation-log.md
opengrok_update_memory
Write or append; auto-timestamps investigation-log.md entries
File
Size Limit
Purpose
active-task.md
≤ 4 KB
Current task state: task:, last_symbol:, next_step:, open_questions:, status:
investigation-log.md
≤ 32 KB
Append-only log of findings, grouped by ## YYYY-MM-DD HH:MM: headings
Delta encoding returns [unchanged] on repeated reads of unmodified content. Richness-scored trimming keeps the highest-value log entries when space is tight.
Core
Variable
Default
Description
OPENGROK_BASE_URL
(blank)
OpenGrok server base URL (required). Supplied by the setup wizard or VS Code settings.
OPENGROK_USERNAME
(blank)
Authentication username. Leave unset for anonymous access.
OPENGROK_PASSWORD
(blank)
Authentication password. Prefer OS keychain via opengrok-mcp setup.
OPENGROK_PASSWORD_FILE
(blank)
Path to a file containing the OpenGrok password (file-mounted secret for CI/containers). Alternative to OPENGROK_PASSWORD.
OPENGROK_VERIFY_SSL
true
Set false to disable TLS verification for self-signed certs.
OPENGROK_TIMEOUT
30
HTTP request timeout in seconds.
Code Mode & Performance
Variable
Default
Description
OPENGROK_CODE_MODE
true
Code Mode (2–5 tools: opengrok_api + opengrok_execute + 3 memory tools when enabled). Set false for the 26 legacy standard tools.
Project picker at opengrok_api startup and env.opengrok.elicit() in sandbox.
OPENGROK_ENABLE_SAMPLING
false
MCP Sampling for error explanation, graph summarization, and zero-result recovery.
OPENGROK_ENABLE_FILES_API
false
FileReferenceCache for investigation-log.md (SHA-256 content-addressed).
OPENGROK_SAMPLING_MODEL
—
Model preference for sampling calls.
OPENGROK_SAMPLING_MAX_TOKENS
256
Token budget for sampling responses (max: 4096).
OpenGrok API
Variable
Default
Description
OPENGROK_API_VERSION
v1
REST API version. Use v2 for opengrok_call_graph.
Security & Audit
Variable
Default
Description
OPENGROK_AUDIT_LOG_FILE
—
File path for structured audit log (CSV or JSON).
OPENGROK_STRICT_SSRF
false
Reject base URLs and redirects resolving to private/loopback IP ranges (default: warn-only).
Logging
Variable
Default
Description
OPENGROK_LOG_LEVEL
info
Set debug for verbose structured logging to stderr.
Proxy
Variable
Default
Description
HTTP_PROXY
—
HTTP proxy for outbound requests.
HTTPS_PROXY
—
HTTPS proxy for outbound requests.
VS Code users can set opengrok-mcp.baseUrl, opengrok-mcp.codeMode, opengrok-mcp.contextBudget, opengrok-mcp.memoryBankDir, opengrok-mcp.defaultProject, opengrok-mcp.responseFormatOverride, opengrok-mcp.compileDbPaths, opengrok-mcp.enableObservationMasker, and opengrok-mcp.observationMaskerTurns in VS Code settings instead. Secret values such as the password are never written to VS Code settings.
MCP SDK Note: This version uses @modelcontextprotocol/sdk v1.30.0 (v1 line).
By default the server communicates over stdio. For shared team deployments, the HTTP transport layer is available as a library API (startHttpTransport() in src/server/transport/http-transport.ts) but is not yet wired into the CLI entry point — OPENGROK_HTTP_PORT is documented below but main.ts does not yet read it to start the HTTP server automatically. Use startHttpTransport() directly in custom deployments.
Session Management
Each HTTP client receives an isolated McpServer instance (per-session factory pattern)
Sessions expire after 30 minutes of inactivity; OPENGROK_HTTP_MAX_SESSIONS caps concurrent sessions (default: 100)
GET /mcp/sessions returns JSON with active session count and oldest session age
In resource server mode, this server validates JWTs issued by your own IdP — there is no built-in /token endpoint. When OPENGROK_JWT_ISSUER is set, tokens from other issuers are rejected. RFC 9728 protected resource metadata is served at /.well-known/oauth-protected-resource.
RBAC Roles
Role
Permissions
admin
Full access to all tools and configuration
developer
All search, read, memory, and code tools
readonly
Search and read tools only — no memory writes, no code execution
Unknown or missing tokens are rejected with 403 Forbidden. When no authentication is configured, unauthenticated requests are granted admin (local dev mode).
CORS
Browser-based clients are gated by an origin allowlist (OPENGROK_ALLOWED_ORIGINS, comma-separated). Without auth configured, loopback origins (localhost, 127.0.0.1, [::1]) are allowed for local development; once auth is configured (OPENGROK_HTTP_AUTH_TOKEN or RBAC tokens), loopback is no longer implicit — list every allowed origin explicitly, including local ones.
Area
Protection
SSRF
DNS rebinding detection + IPv6-mapped address blocking in buildSafeUrl; strict mode via OPENGROK_STRICT_SSRF
Path traversal
NFC normalization + bidirectional Unicode character blocking in assertSafePath
HTML injection
Entity decoding on all parser text nodes before display
Prompt injection
Markdown-field escaping in all formatters
Token comparison
crypto.timingSafeEqual for all Bearer token comparisons
CORS
Allowlist via OPENGROK_ALLOWED_ORIGINS — no wildcard in production
Security headers
X-Content-Type-Options, X-Frame-Options, CSP on HTTP responses
Credential encryption
AES-256-GCM with auto-upgrade from older encrypted files
QuickJS WASM VM — no filesystem, no network, method allowlist only; 62 s timeout, 8 MB buffer
Audit logs
Injection-escaped structured audit entries
For the full security architecture (threat model, defense layers, hardening guide), see SECURITY.md.
Sandbox trust recommendation: When configuring OpenGrok MCP in VS Code's MCP settings, you may set sandboxEnabled: true which auto-approves tool calls without confirmation prompts. This is safe because all tool execution occurs inside the QuickJS WASM sandbox with no host access — the LLM cannot execute arbitrary system commands through this server.
VS Code Integration
Command
Action
OpenGrok: Open Configuration
Interactive settings GUI
OpenGrok: Test Connection
Validate API access and token validity
OpenGrok: Show Server Logs
Expose background process stdout/stderr
OpenGrok: Status Menu
Quick-access status menu from the status bar
OpenGrok: Check for Updates
Manually trigger an update check
[!NOTE]
VS Code manages tool authorizations per workspace. If you open a different repository, re-check the OpenGrok box in the Copilot tools panel.
The configuration panel and VS Code Settings UI cover the same settings: use the panel for guided setup, secrets, testing, and reload prompts. Use opengrok-mcp.* settings in settings.json for workspace overrides, Settings Sync, and scripted defaults. Code Mode is recommended; disabling it uses legacy standard tools and excludes new Code Mode-only capabilities.
Troubleshooting
[!TIP]
Run opengrok-mcp status to check connectivity and confirm which MCP clients are configured.
[!WARNING]
After reloading VS Code or updating the extension, tools may temporarily disappear from the Copilot tools list. Click the tools icon, select "Update Tools", then run Developer: Reload Window to restore them.
Connection failed — Verify OPENGROK_BASE_URL. Check that your VPN or proxy is not blocking the endpoint.
401 Unauthorized — Run OpenGrok: Open Configuration to re-enter credentials.
Self-signed SSL certificate errors — Set opengrok-mcp.verifySsl to false in VS Code settings, or OPENGROK_VERIFY_SSL=false in your MCP client config.
Slow queries or timeouts — Narrow the scope with file_type filtering or target a specific project. Check indexing status with opengrok_index_health.
✅ 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.
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Fragen
Wie installiere ich OpenGrok MCP Server?
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.