MCP Gtags Server

mcp-gtags-server

Stop letting your AI agent grep. Give it an index.

mcp-name: io.github.harshithsunku/mcp-gtags-server

# If you don't have uv yet (one-time, no sudo):

curl -LsSf https://astral.sh/uv/install.sh | sh

{ "mcpServers": { "gtags": { "command": "uvx", "args": ["mcp-gtags-server"] } } }

*One user-level config entry, no sudo, no pre-installed anything — the whole toolchain installs itself into user space on first use, and every repo you open is served automatically.*

📖 [Full documentation](https://harshithsunku.github.io/mcp-gtags-server/) — install for every client, the tool reference, output format, kernel features, configuration and troubleshooting.

Every AI coding agent — Claude Code, Cursor, Codex, you name it — answers *"where is this function defined?"* the same way: grep the entire tree. On a million-line C/C++ codebase that's a full scan per question, and the output is a firehose: every comment, string literal, and unrelated match, dumped straight into the model's context window.

mcp-gtags-server replaces those scans with indexed lookups powered by GNU Global (gtags) — the same tags engine kernel and systems developers have trusted for decades — exposed to agents over the Model Context Protocol. Built for the codebases LSP-based tools can't handle: kernel-scale C/C++, trees that don't currently compile, machines you can't sudo on.

• ~100× faster per query — milliseconds instead of seconds, at any codebase size
• Radically less noise — the definition, not 7,873 lines of matches
• Speaks kernel — #ifdef guard stacks with .config filtering, macro-generated symbols (sys_read → its SYSCALL_DEFINE3 site) that no other tagging tool resolves, and definitions the parser misses recovered from their EXPORT_SYMBOL site via ctags
• Zero index management — first query builds the index, every query auto-refreshes it
• Correctness measured in CI — a 64-case golden eval covering all 8 tools against a pinned kernel: 100% recall, 100% precision@1 (docs/capability.md)
• Works everywhere MCP does — Claude Code, Claude Desktop, Cursor, any MCP client

The numbers (real Linux kernel, not a toy)

Measured on a full Linux kernel checkout — 65,163 C/C++ files, 37.1 million lines — warm page cache:

One-time index build: 66 s for the whole kernel. Incremental refresh after edits: well under a second. Reproduce it yourself with scripts/benchmark.sh:

./scripts/benchmark.sh /path/to/linux tcp_v4_rcv kmalloc ext4_readdir

The speed is nice. The real win is precision: an agent that gets 5 exact lines instead of 7,873 noisy ones keeps its context window for actual reasoning.

And the answers are *measured*, not assumed: CI runs a 64-case golden eval against pinned kernel v6.16 on every push — currently 100% recall, 100% precision@1 across definitions, macro resolution, export recovery, references, callers, callees, definition bodies, #ifdef guards, and reachability, covering all 8 tools. The full methodology, numbers, and honest limitations live in docs/capability.md.

Quick start (60 seconds)

Option A — one config entry (recommended)

Add the server once, at user level, and you're done — no installer, no pre-installed gtags, no per-repo setup. The only prerequisite is uv (or use Option B, which installs it for you).

# Claude Code (once per device, all repos):

claude mcp add --scope user gtags -- uvx mcp-gtags-server

// Cursor (~/.cursor/mcp.json), or any MCP client's global settings:

{ "mcpServers": { "gtags": { "command": "uvx", "args": ["mcp-gtags-server"] } } }

Or click the Cursor one-click install badge at the top of this page.

On the very first tool call the server bootstraps everything else by itself: GNU Global (prebuilt user-space binaries — no compiler, no sudo), universal-ctags, and Pygments, all into ~/.gtags-mcp. While that one-time install runs (a few seconds on most platforms), tool calls return a *"toolchain is being installed — retry shortly"* status instead of failing. Opt out with --no-auto-setup or GTAGS_MCP_AUTO_SETUP=0.

The prebuilt Linux binaries run on any distro with glibc ≥ 2.28 (RHEL/Rocky 8+, Ubuntu 18.10+, Debian 10+). On older hosts — or if a downloaded binary fails its post-install execution check — setup automatically compiles GNU Global from source instead, which only needs make and a C compiler.

Option B — install the plugin (server + skill + slash commands)

The plugin bundles this server, a "C/C++ code navigation" skill that tells the agent which tool answers which question, and two slash commands (/gtags:impact, /gtags:explain). Installing it registers the MCP server for you — there is no config file to edit.

Install one way, not both. A plugin *and* a manual entry run two servers,

and the agent sees every tool twice. Switching to the plugin? Remove the

manual entry first (claude mcp remove gtags).

Option C — one-line installer (shared background server)

One command. No sudo. Works everywhere — restricted corporate machines, containers, build servers:

curl -fsSL https://raw.githubusercontent.com/harshithsunku/mcp-gtags-server/main/scripts/install.sh | bash

Everything lands in your home directory — the server (via uv), GNU Global, universal-ctags, and Pygments (in ~/.gtags-mcp). When it finishes, a shared background HTTP server is running that every client and IDE window on the machine can point at (http://127.0.0.1:8383/mcp), and the exact client configuration is printed to your console.

Re-run the same command any time:

• Up to date? → *"Already installed and up to date — nothing to install"*, and the config is printed again.
• New release on GitHub/PyPI? → the package updates, an outdated gtags toolchain is wiped and reinstalled automatically, and the background server restarts on the new version.

Slash commands (MCP prompts)

Available with any install, in clients that support MCP prompts (Claude Code, Cursor). They cost no tool-schema context:

One config, many repos

However you install it, one user-level entry serves every repo you open — 20 repos need zero extra installs and zero extra config. Each tool call resolves its project root down this ladder:

1. project_root argument on the tool call (agents pass this to target any tree)
2. --root flag / GTAGS_MCP_ROOT env var
3. root in a config file *(note: pinning a root here defeats multi-repo)*
4. The client's workspace roots (MCP roots protocol) — IDEs that advertise their open folders get the right repo automatically, even on the shared HTTP server; with several folders open, agents are asked to pass project_root. Roots exist only for clients on protocol revisions up to 2025-11-25: the 2026-07-28 revision deprecated them, so those clients skip this step (stdio servers still resolve through step 5; on the shared HTTP server, agents pass project_root)
5. Walk up from the server's working directory to the nearest .git/GTAGS — this is why stdio servers spawned by Claude Code/Cursor inside a repo just work

Step 5 can be switched off with --no-cwd-fallback / GTAGS_MCP_CWD_FALLBACK=0 (the plugin sets it): the tools then ask for project_root instead of indexing whatever directory the server happens to run in. Plugin clients launch the server from the plugin's own folder, which is never your project.

That's it. No indexing step, no configuration. Ask your agent *"who calls tcp_v4_rcv?"* — the first query in any repo builds that repo's index automatically, and every query after that is answered in milliseconds. Run mcp-gtags-server doctor any time to see what the server detects, or mcp-gtags-server config to re-print the client configuration.

Background server details (network access, port, lifecycle)

The installer runs mcp-gtags-server --transport http --host 127.0.0.1 --port 8383 in the background (pid: ~/.gtags-mcp/server.pid, log: ~/.gtags-mcp/server.log). Environment overrides for the installer:

Security note: the HTTP endpoint is unauthe