Skip to main content

​
Syntax

gitnexus mcp

​
Description

Starts the MCP server in stdio mode, serving all indexed repositories. This command is typically invoked automatically by your AI editor’s MCP configuration. The MCP server:
  • Loads all indexed repositories from the global registry (~/.gitnexus/registry.json)
  • Exposes all GitNexus tools via the Model Context Protocol
  • Discovers new repositories lazily (repos indexed after the server starts are picked up automatically)
  • Runs continuously until the editor closes

​
Multi-Repo Support

The MCP server serves all indexed repositories automatically. When you have multiple repos indexed:
  • Tools accept an optional repo parameter to specify which repository to query
  • If only one repo is indexed, the repo parameter is optional
  • If multiple repos are indexed and no repo is specified, the tool returns an error

​
Error Handling

The MCP server is designed to be resilient:
  • Uncaught exceptions are logged but don’t crash the server
  • KuzuDB lock conflicts degrade gracefully
  • Zero repos — The server starts even with no indexed repos. It prints a warning but remains running, and tools will discover repos lazily.

​
How Editors Use It

Typical MCP configuration: 
{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}
The editor spawns this command as a subprocess and communicates via stdio using the MCP protocol.

​
Manual Usage

You typically don’t run this command manually. Use gitnexus setup to configure your editor to run it automatically. However, you can test it manually: 
gitnexus mcp
The server will print to stderr (since stdout is reserved for MCP protocol messages): 
GitNexus: MCP server starting with 2 repo(s): my-app, backend-api
Or if no repos are indexed: 
GitNexus: No indexed repos yet. Run `gitnexus analyze` in a git repo — the server will pick it up automatically.

​
MCP Tools Exposed

ToolDescription
list_reposList all indexed repositories
queryProcess-grouped hybrid search (BM25 + semantic + RRF)
context360-degree symbol view — categorized refs, process participation
impactBlast radius analysis with depth grouping and confidence
detect_changesGit-diff impact — maps changed lines to affected processes
renameMulti-file coordinated rename with graph + text search
cypherRaw Cypher graph queries
See the MCP Tools Reference for detailed documentation.

​
MCP Resources Exposed

ResourceDescription
gitnexus://reposList all indexed repositories
gitnexus://repo/{name}/contextCodebase stats, staleness check, and available tools
gitnexus://repo/{name}/clustersAll functional clusters with cohesion scores
gitnexus://repo/{name}/cluster/{name}Cluster members and details
gitnexus://repo/{name}/processesAll execution flows
gitnexus://repo/{name}/process/{name}Full process trace with steps
gitnexus://repo/{name}/schemaGraph schema for Cypher queries
See the MCP Resources Reference for detailed documentation.

​
MCP Prompts Exposed

PromptDescription
detect_impactPre-commit change analysis — scope, affected processes, risk level
generate_mapArchitecture documentation from the knowledge graph with mermaid diagrams
See the MCP Prompts Reference for detailed documentation.

​
Lazy Repository Discovery

The MCP server doesn’t require a restart when you index new repositories. Tools call refreshRepos() internally before each operation, automatically discovering repos indexed after the server started. This means you can:
  1. Start your editor (MCP server starts)
  2. Index a new repo: gitnexus analyze
  3. Use MCP tools immediately — no restart needed

Build docs developers (and LLMs) love

Get started for freeTalk to us