Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@opengrok-mcp find where parseConfig is defined"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets an AI agent search and read source code indexed by an OpenGrok instance. Read-only, stdio transport.
Tested against OpenGrok 1.14. It uses the REST search API and the /raw file route, both of which
work anonymously on a default install.
Tool | Purpose |
| Search by |
| Find files by name or path pattern. |
| Read a file (line-numbered) by the path returned from search, with an optional line range. |
| List the project names on the instance. |
Searches are scoped to the configured default project(s); pass projects to pick others or
all_projects: true to search everything.
Related MCP server: Semantic Code Search MCP Server
Requires Node.js 20+.
git clone https://github.com/jenkeeri/opengrok-mcp.git
cd opengrok-mcp
npm install && npm run buildAll settings are environment variables, normally set in your MCP client's server entry:
Variable | Required | Description |
| yes | Base URL, e.g. |
| no | Comma-separated default project(s). Empty means all projects. |
| no | Free text appended to the server instructions the agent sees. Use it to describe your project layout (what each project is, naming conventions). |
| no | Bearer token, if the instance needs one. |
| no | Basic auth, if the instance needs it. |
| no | Per-request timeout (default |
Example MCP client entry:
{
"mcpServers": {
"opengrok": {
"command": "node",
"args": ["/path/to/opengrok-mcp/dist/index.js"],
"env": {
"OPENGROK_URL": "https://opengrok.example.com",
"OPENGROK_DEFAULT_PROJECT": "myproject",
"OPENGROK_INSTRUCTIONS": "Project 'myproject' is the main branch; 'myproject-1.2' is a release branch."
}
}
}
}Use the REST parameter names projects, def, symbol and start. The web UI names (project,
defs, refs) are silently ignored by the API, which makes project filtering appear broken.
type takes an OpenGrok analyzer name (c, cxx, java, python, ...); an unknown name
returns zero results.
def and symbol rely on OpenGrok's language-aware indexing; use full for file types it cannot parse.
npm test # unit tests (synthetic fixtures, no network)
npm run typecheck
npm run buildGPL-3.0, see LICENSE.
Find files by path or file name. Returns file paths only. Examples: "main.cpp" (name), "*.sql" (wildcard), "src/net" (directory), "/.test..py/" (regex). Default scope: none (all projects).
| Name | Required | Description | Default |
|---|---|---|---|
| type | No | File type (analyzer name), as for opengrok_search. | |
| start | No | Offset of the first file to return (default 0); use the value a previous page suggested. | |
| projects | No | Projects to search (default: none (all projects)). Names from opengrok_list_projects. | |
| max_results | No | Files per page (default 30, max 100). | |
| all_projects | No | Search every project instead of the default. Ignored if projects is set. | |
| path_pattern | Yes | Path or name pattern. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, non-destructive, and open-world behavior, so the safety profile is covered. The description usefully adds the return shape ("file paths only") and default scope, both of which matter for a tool with no output schema. Pagination behavior lives in the schema rather than the description.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then return shape, then a compact single-line example block, then the scope default. Every sentence carries information and nothing is repeated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the "returns file paths only" statement is essential and present, and the scope default is called out. Pagination and project-selection mechanics are handled by the schema, so the description is sufficient, though it does not address result volume or empty-result behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so the structured fields already document all six parameters. The description still earns credit by clarifying the format of path_pattern (name vs wildcard vs directory vs regex), which the schema only labels as "Path or name pattern" — a genuine semantic addition.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ("Find files by path or file name") and immediately scopes the result ("Returns file paths only"). This implicitly separates it from opengrok_get_file (content retrieval) and opengrok_search (content matching), though it never names those siblings explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides concrete input examples and states the default scope ("none (all projects)"), which implies usage context. However there is no explicit guidance on when to prefer this over opengrok_search or opengrok_get_file, so the routing decision is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a file's content (line-numbered) by the full path returned from search, e.g. "//dir/file.c". Use start_line/end_line for large files; output is cut at 30000 characters.
| Name | Required | Description | Default |
|---|---|---|---|
| end_line | No | Last line (1-based, inclusive). | |
| file_path | Yes | Full path as returned by search, starting with "/<project>/". | |
| start_line | No | First line (1-based, inclusive). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description adds real behavioral context beyond them: line-numbered output and a hard 30000-character truncation limit, which the agent needs to plan pagination. It doesn't cover error behavior on bad paths.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with the essential path-source constraint front-loaded and the pagination/truncation caveat second. Every clause carries information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description must carry the return format, and it does: line-numbered content with a 30000-character cap. Complete enough to call correctly, with only error-handling and exact truncation semantics left implicit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description reinforces file_path's required format with an example and explains the purpose of start_line/end_line for large files, tying parameters to behavior rather than restating types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Read a file's content') plus the key qualifier that the path must be the full path returned from search, which separates it from opengrok_find_file. It does not explicitly name the sibling tools, but the resource and path-source constraint make its role distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context for using start_line/end_line on large files and tells the agent where file_path comes from ('returned from search'). It stops short of an explicit when-not-to-use statement against opengrok_find_file or opengrok_search, but the routing guidance is strong.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the project names available on the OpenGrok instance (valid values for the projects argument).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, openWorldHint and destructiveHint=false, so the safety profile is fully covered. The description adds that the payload is project names usable as the projects argument, which is useful but does not describe ordering, format, or whether results reflect a live instance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, zero filler, and the key output semantic is front-loaded immediately after the core action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only listing tool with no output schema, the description conveys enough: what is returned (project names) and what they are for. Only the shape/ordering of the returned list is unspecified, which is a minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the baseline of 4 applies. The description nevertheless explains the role of the output values relative to the projects argument of sibling tools, which is mildly more than the empty schema conveys.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb+resource pair ('List the project names available on the OpenGrok instance'), which is easily separable from the search/get_file/find_file siblings. It does not explicitly call out those siblings, so it lands at 4 rather than 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The parenthetical '(valid values for the projects argument)' gives concrete context: this is the discovery step that feeds the projects parameter of the search tool. No explicit when-not or named alternatives are given, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search source code. Provide at least one of full, def, symbol, path, hist; fields combine with AND.
full: full-text Lucene query. Supports wildcards (foo*), phrases ("a b"), AND/OR/NOT (uppercase), fuzzy (word~), regex (/re/).
def: where a symbol is DEFINED. symbol: where a symbol is referenced or defined. Both need language-aware indexing, so they return nothing for file types OpenGrok cannot parse; fall back to full.
path: restrict by file path (e.g. "src/net", "*.cpp").
hist: search commit messages.
type: OpenGrok analyzer name, e.g. c, cxx, java, python, sh, xml, json, yaml, plain. An unknown name yields zero results. Default scope: none (all projects). Results list files with matching lines (line numbers where available).
| Name | Required | Description | Default |
|---|---|---|---|
| def | No | Symbol whose definition to find. | |
| full | No | Full-text query. | |
| hist | No | History/commit message query. | |
| path | No | Path filter. | |
| type | No | File type (analyzer name). | |
| start | No | Offset of the first file to return (default 0); use the value a previous page suggested. | |
| symbol | No | Symbol to find references to. | |
| projects | No | Projects to search (default: none (all projects)). Names from opengrok_list_projects. | |
| max_results | No | Files per page (default 20, max 100). | |
| all_projects | No | Search every project instead of the default. Ignored if projects is set. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. Beyond that, the description discloses important behavioral limits: def and symbol return nothing for file types OpenGrok cannot parse, unknown analyzer names yield zero results, default scope is all projects, and results list files with matching lines and line numbers where available. These details materially help an agent predict outcomes and avoid wasted calls.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and then organized as compact bullet points for each query field. Despite covering many parameters, every sentence contributes useful meaning, and there is no redundant or filler language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 parameters, no required parameters, and no output schema, the description covers query modes, AND combination, fallback behavior, default scope, and the basic return shape. It omits pagination semantics for start and max_results and does not mention opengrok_list_projects for discovering project names, though the schema covers those details. It is largely complete but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description adds substantial semantic detail beyond the schema. It explains Lucene syntax for full (wildcards, phrases, uppercase AND/OR/NOT, fuzzy, regex), the semantic difference between def and symbol, path examples such as 'src/net' and '*.cpp', and concrete analyzer names for type. This is far richer than the terse schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Search source code.' It clearly explains the distinct query modes (full, def, symbol, path, hist, type) and how they combine with AND. It does not explicitly distinguish itself from siblings such as opengrok_find_file or opengrok_get_file, so it falls short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear invocation guidance: 'Provide at least one of full, def, symbol, path, hist; fields combine with AND,' and tells the agent to fall back to full when def or symbol cannot work due to language-aware indexing limits. It does not name any sibling tool as an alternative or state when not to use this tool, so it is not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0opengrok_find_fileopengrok_get_fileopengrok_list_projectsopengrok_searchScored across 4 tools
Each tool targets a distinct action: search content, read a file, find files by path, list projects. The only overlap is that opengrok_search's 'path' parameter can also filter by path, which could be confused with opengrok_find_file, but the descriptions clarify that search returns matching lines while find_file returns only paths.
All tools use the opengrok_ prefix and snake_case. Three follow verb_noun (get_file, find_file, list_projects), while search is just a verb, a minor deviation from the otherwise consistent pattern.
Four tools is well-scoped for a read-only code search server. Each tool has a clear, non-redundant role: search content, retrieve file contents, find files, and list projects.
The core read-only workflows (search, read, find, list projects) are covered. Minor gaps exist, such as no direct file history/blame tool and no explicit directory listing beyond find_file patterns, but agents can work around these with existing tools.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Search indexed code, trace dependencies, assess change impact, and recall repository memory.
Search GitHub, npm, PyPI, StackOverflow, ArXiv from one MCP — built for coding agents.
