Cursor Setup

Cursor supports MCP tools and agent skills, providing a powerful GitNexus integration.

Support Level: MCP + Skills (hooks not supported)

Quick Setup

Run the setup command to configure everything automatically:

npx gitnexus setup

This will:

Detect Cursor installation (checks for ~/.cursor/)
Write ~/.cursor/mcp.json with GitNexus MCP configuration
Install skills to ~/.cursor/skills/gitnexus/

Example output

GitNexus Setup
==============

Configured:
  + Cursor
  + Cursor skills (6 skills → ~/.cursor/skills/)

Summary:
  MCP configured for: Cursor
  Skills installed to: Cursor skills

Next steps:
  1. cd into any git repo
  2. Run: gitnexus analyze
  3. Open the repo in your editor — MCP is ready!

Manual MCP Configuration

Create or edit ~/.cursor/mcp.json (global configuration):

{
  "mcpServers": {
    "gitnexus": {
      "command": "npx",
      "args": ["-y", "gitnexus@latest", "mcp"]
    }
  }
}

Global Configuration: This configuration is global — it works for all projects on your machine. Cursor will spawn the MCP server automatically.

Windows Configuration

On Windows, use:

{
  "mcpServers": {
    "gitnexus": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "gitnexus@latest", "mcp"]
    }
  }
}

The gitnexus setup command handles this automatically.

Agent Skills

GitNexus provides 6 agent skill files for Cursor:

Skill	Purpose
`gitnexus-exploring`	Navigate unfamiliar code using the knowledge graph
`gitnexus-debugging`	Trace bugs through call chains
`gitnexus-impact-analysis`	Analyze blast radius before changes
`gitnexus-refactoring`	Plan safe refactors using dependency mapping
`gitnexus-guide`	General guidance on tool usage
`gitnexus-cli`	CLI command reference

Skills are installed to ~/.cursor/skills/gitnexus-{skillName}/ by:

gitnexus setup — Global skills for all projects
gitnexus analyze — Project-level skills in .cursor/skills/

Cursor automatically discovers skills from both ~/.cursor/skills/ (global) and .cursor/skills/ (project).

Global vs Project Configuration

Global Configuration (Recommended)

Global configuration applies to all projects:

MCP: ~/.cursor/mcp.json
Skills: ~/.cursor/skills/gitnexus/

This is the recommended approach for most users.

Project Configuration

Project configuration applies to a single repository:

Skills: .cursor/skills/gitnexus/ (installed by gitnexus analyze)
Context: AGENTS.md (installed by gitnexus analyze)
Rules: .cursorrules (optional, for project-specific instructions)

Cursor does not support project-level MCP configuration. MCP must be configured globally in ~/.cursor/mcp.json.

Multi-Repo Support

The MCP server automatically serves all indexed repositories from the global registry (~/.gitnexus/registry.json).

With One Indexed Repo

The repo parameter is optional:

// Both are equivalent
query({ query: "auth" })
query({ query: "auth", repo: "my-app" })

With Multiple Indexed Repos

Specify which repo to query:

query({ query: "auth", repo: "backend" })
context({ name: "validateUser", repo: "frontend" })
impact({ target: "AuthService", direction: "upstream", repo: "shared" })

List all indexed repos:

list_repos()

Or read the repos resource:

READ gitnexus://repos

Verification

Test your Cursor integration:

Index a repository

cd /path/to/your/repo
npx gitnexus analyze

Open in Cursor

Open the repository in Cursor

Test MCP connection

Ask Cursor:

“List all indexed repositories”

This should trigger the list_repos MCP tool.

Test skills

Ask Cursor:

“How should I use GitNexus to understand this codebase?”

Cursor should reference the installed skills.

Test resources

Ask Cursor:

“Read gitnexus://repos”

This should show your indexed repositories with stats.

Available Tools

All 7 GitNexus tools are available in Cursor:

Tool	Purpose
`list_repos`	Discover all indexed repositories
`query`	Process-grouped hybrid search (BM25 + semantic + RRF)
`context`	360-degree symbol view with categorized refs
`impact`	Blast radius analysis with depth grouping
`detect_changes`	Git-diff impact analysis
`rename`	Multi-file coordinated rename
`cypher`	Raw Cypher graph queries

See Tools Overview for detailed usage.

Available Resources

All 7 GitNexus resources are available:

Resource	Purpose
`gitnexus://repos`	List all indexed repositories
`gitnexus://repo/{name}/context`	Codebase stats and staleness check
`gitnexus://repo/{name}/clusters`	All functional clusters
`gitnexus://repo/{name}/cluster/{name}`	Cluster details
`gitnexus://repo/{name}/processes`	All execution flows
`gitnexus://repo/{name}/process/{name}`	Process trace
`gitnexus://repo/{name}/schema`	Graph schema for Cypher

See Resources Overview for details.

Project Context Files

When you run gitnexus analyze, two context files are created:

AGENTS.md

Contains:

Codebase overview and stats
Tool reference table
Skills checklist
Graph schema reference

Cursor reads this file automatically as project context.

.cursorrules (Optional)

You can create .cursorrules to add project-specific instructions:

# GitNexus Integration

This project is indexed by GitNexus. Always start by:

1. Reading gitnexus://repo/{name}/context to check staleness
2. Using the appropriate skill for your task (see AGENTS.md)
3. Following the skill's workflow and checklist

Available skills:
- gitnexus-exploring: Understand architecture
- gitnexus-debugging: Trace bugs
- gitnexus-impact-analysis: Blast radius before changes
- gitnexus-refactoring: Safe refactoring workflows

Updating GitNexus

The MCP configuration uses gitnexus@latest, so you automatically get the latest version:

"args": ["-y", "gitnexus@latest", "mcp"]

To force an update:

npm cache clean --force
npx gitnexus@latest --version

Restart Cursor to pick up the new version.

Troubleshooting

MCP server not starting

Verify Node.js: node --version (requires >= 18)
Check npx works: npx gitnexus --version
Test MCP manually: npx gitnexus mcp (should not exit immediately)
Check ~/.cursor/mcp.json syntax (must be valid JSON)

Tools not appearing

Verify ~/.cursor/mcp.json exists and has correct content
Restart Cursor after configuration changes
Check Cursor MCP logs (if available)

Skills not loading

Verify skills directory: ls ~/.cursor/skills/gitnexus-exploring/SKILL.md
Check skill format (must have SKILL.md filename)
Restart Cursor

”No repositories indexed” error

Run npx gitnexus analyze in your repository
Verify index exists: ls .gitnexus/meta.json
Check global registry: cat ~/.gitnexus/registry.json

Differences from Claude Code

Cursor does not support:

PreToolUse Hooks — No automatic enrichment of grep/glob/bash calls
Session Hooks — No automatic session context injection

Cursor does support:

All MCP Tools — Full access to query, context, impact, etc.
All MCP Resources — Can read all gitnexus:// resources
Agent Skills — Can load and follow skill workflows

To get knowledge graph enrichment in Cursor, explicitly use GitNexus tools in your queries. For example: “Use query to find auth code, then use context on the results.”

Next Steps

Using the Tools

Learn how to use GitNexus tools effectively

Multi-Repo Usage

Work with multiple indexed repositories

Agent Skills

Understand the installed skill workflows

Resources

Explore MCP resources for structured data

Get Started

Core Concepts

CLI Usage

MCP Integration

Agent Skills

Web UI

Advanced

Quick Setup

Manual MCP Configuration

Windows Configuration

Agent Skills

Global vs Project Configuration

Global Configuration (Recommended)

Project Configuration

Multi-Repo Support

With One Indexed Repo

With Multiple Indexed Repos

Verification

Available Tools

Available Resources

Project Context Files

AGENTS.md

.cursorrules (Optional)

Updating GitNexus

Troubleshooting

MCP server not starting

Tools not appearing

Skills not loading

”No repositories indexed” error

Differences from Claude Code

Next Steps

Using the Tools

Multi-Repo Usage

Agent Skills

Resources

Build docs developers (and LLMs) love

Get Started

Core Concepts

CLI Usage

MCP Integration

Agent Skills

Web UI

Advanced

​Quick Setup

​Manual MCP Configuration

​Windows Configuration

​Agent Skills

​Global vs Project Configuration

​Global Configuration (Recommended)

​Project Configuration

​Multi-Repo Support

​With One Indexed Repo

​With Multiple Indexed Repos

​Verification

​Available Tools

​Available Resources

​Project Context Files

​AGENTS.md

​.cursorrules (Optional)

​Updating GitNexus

​Troubleshooting

​MCP server not starting

​Tools not appearing

​Skills not loading

​”No repositories indexed” error

​Differences from Claude Code

​Next Steps

Using the Tools

Multi-Repo Usage

Agent Skills

Resources

Build docs developers (and LLMs) love

Quick Setup

Manual MCP Configuration

Windows Configuration

Agent Skills

Global vs Project Configuration

Global Configuration (Recommended)

Project Configuration

Multi-Repo Support

With One Indexed Repo

With Multiple Indexed Repos

Verification

Available Tools

Available Resources

Project Context Files

AGENTS.md

.cursorrules (Optional)

Updating GitNexus

Troubleshooting

MCP server not starting

Tools not appearing

Skills not loading

”No repositories indexed” error

Differences from Claude Code

Next Steps