<div align="center"> <img src="images/icon.png" width="120" alt="OpenGrok MCP Server logo">

OpenGrok MCP Server

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.

</div>

---

Quick Start

Option 1 — VS Code Extension

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.

Option 2 — npm / npx CLI

npm install -g opengrok-mcp-server
opengrok-mcp setup      # interactive wizard: URL, credentials, MCP client registration

Or run without installing:

npx opengrok-mcp-server setup

Other CLI commands:

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

<details> <summary>Tool Reference</summary>

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. | | opengrok_browse_directory | View folder structure and contained files. Supports cursor / limit pagination. | | opengrok_list_projects | List all indexed repositories. | | opengrok_get_file_annotate | Line-by-line blame annotation. Supports revision, start_line/end_line range, includeContent. | | opengrok_get_file_symbols | Extract classes, functions, macros, and structs from a file. Supports cursor pagination. | | opengrok_search_suggest | Query autocomplete recommendations. Supports context passthrough for ranking. |

Compound Tools

These merge multiple API calls into a single operation.

| Tool | What it replaces | Savings | | ---- | ---------------- | ------- | | opengrok_get_symbol_context | Search definition + read source + fetch headers + get references | ~92% fewer tokens | | opengrok_search_and_read | Search + read surrounding context (cap: OPENGROK_SEARCH_AND_READ_CAP) | ~92% fewer tokens | | opengrok_batch_search | 2–5 parallel searches, deduplicated results | ~73% fewer tokens | | opengrok_index_health | Latency, connectivity, staleness score | Diagnostic |

Investigation Tools

| Tool | Purpose | | ---- | ------- | | opengrok_what_changed | Recent line changes grouped by commit — author, date, SHA, changed lines with context | | opengrok_dependency_map | BFS traversal of #include/import chains up to depth 3; directed graph with uses/used_by | | opengrok_search_pattern | Regex code search; returns file:line:content matches | | opengrok_blame | 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.

</details> <details> <summary>Code Mode API</summary>

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.

Search & Discovery

| Method | Returns | | ------ | ------- | | env.opengrok.search(query, opts?) | Full text, defs, refs, symbol, path, hist. Opts: searchType, projects, maxResults (default 5), startIndex, cursor, fileType, sort, maxHitsPerFile, dir, pathFilter, file, expandFunction | | env.opengrok.batchSearch(queries[], opts?) | One result-set per query (max 10), run in parallel on the host. Per-query expandFunction: true includes enclosing function context | | env.opengrok.findFile(pattern, opts?) | { totalCount, results: [{project, path}], cursor? } | | env.opengrok.searchSuggest(query, opts?) | { query, field, suggestions, time }. Opts: field, project/projects, context (other-field values for ranking) | | env.opengrok.getAllMatchesInFile(project, path, query, opts?) | 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, `getFileDif