codex-nav-mcp-server

An MCP (Model Context Protocol) server that exposes tree-sitter-based code navigation as tools for AI assistants. Instead of shelling out to grep/cat/find, AI agents can use three purpose-built tools to explore codebases via AST-level queries.

Tools

code_nav_init

Initializes or refreshes the tree-sitter symbol index for the current working directory. Must be called once at the start of a session before using code_symbols or code_query.

code_symbols

Lists all top-level symbols (functions, structs, classes, enums, traits, etc.) defined in a file or directory. Returns each symbol's name, kind, file path, and line number as JSON.

code_query

Runs an arbitrary tree-sitter S-expression query against source files, returning up to 500 matches with file paths and line numbers.

Prompt

The server also exposes an MCP prompt, codex_nav_code_search, containing guidance on when and how to reach for these tools instead of grep/cat/find. Hosts that surface prompts (e.g. via a slash-command picker) can load it directly; the same text is also sent as the server's instructions during initialization.

Usage

The server communicates over stdio transport, making it compatible with any MCP host (Claude Desktop, VS Code extensions, CLI tools, etc.).

Choosing the directory to index

The server indexes a single working directory, resolved as follows:

1. The CODE_NAV_CWD environment variable, if set.
2. Otherwise, the process's current working directory.

Because MCP hosts typically launch the server with their own (often unrelated) working directory, set CODE_NAV_CWD to the absolute path of the project you want to index. All path arguments are resolved relative to this directory.

Build from source

cargo build --release

The binary is at target/release/codex-nav-mcp-server.

Claude Desktop

Add to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "codex-nav": {
      "command": "/absolute/path/to/codex-nav-mcp-server",
      "args": [],
      "env": {
        "CODE_NAV_CWD": "/absolute/path/to/your/project"
      }
    }
  }
}

Replace /absolute/path/to/codex-nav-mcp-server with the path to the binary (e.g. target/release/codex-nav-mcp-server from the project root), and set CODE_NAV_CWD to the project you want to index (see Choosing the directory to index).

VS Code (Cline / Roo Code / etc.)

Add to your MCP settings file (e.g. .vscode/mcp.json or the extension's global settings):

{
  "servers": {
    "codex-nav": {
      "type": "stdio",
      "command": "/absolute/path/to/codex-nav-mcp-server",
      "args": []
    }
  }
}

Codex CLI

Codex CLI discovers MCP servers from a config file. Add an entry:

{
  "mcpSe

... [View full README on GitHub](https://github.com/0x1337c0d3/An-MCP-server-that-exposes-tree-sitter-based-code-navigation-as-tools-for-AI-assistants.#readme)