Editor Setup

Connect Nomik to Cursor, Windsurf, Claude Desktop, or Antigravity — one command per editor.

Automatic Setup

Terminal

nomik setup-cursor       # Cursor AI
nomik setup-windsurf     # Windsurf AI
nomik setup-claude       # Claude Desktop
nomik setup-antigravity  # Antigravity Editor

Each command auto-detects your OS, locates the correct config file, and writes the MCP server configuration with your Neo4j credentials and active project ID.

In stdio mode (default), the IDE launches the MCP server on demand. You do not need to run nomik serve.

Cursor

Terminal

$ nomik setup-cursor

✓ Created .cursor/mcp.json
  Server:  @nomik-ai/cli (stdio)
  Neo4j:   bolt://localhost:7687
  Project: my-api
  Role:    dev (full access)

Restart Cursor to activate.

Config file location: .cursor/mcp.json (project root)

.cursor/mcp.json

{
  "mcpServers": {
    "nomik": {
      "command": "npx",
      "args": ["-y", "@nomik-ai/cli", "mcp"],
      "env": {
        "NOMIK_GRAPH_URI": "bolt://localhost:7687",
        "NOMIK_GRAPH_USER": "neo4j",
        "NOMIK_GRAPH_PASS": "nomik_local",
        "NOMIK_PROJECT_ID": "my-api",
        "NOMIK_ROLE": "dev",
        "NOMIK_SAMPLING": "false"
      }
    }
  }
}

After restarting Cursor, Nomik tools appear in the AI chat. Every tool description starts with "ALWAYS use this tool when..." — this ensures Cursor's AI prefers Nomik's graph data over manual file reading.

Windsurf

Terminal

$ nomik setup-windsurf

✓ Created ~/.codeium/windsurf/mcp_config.json
  Server:  @nomik-ai/cli (stdio)
  Neo4j:   bolt://localhost:7687
  Project: my-api

Restart Windsurf to activate.

Config file location: ~/.codeium/windsurf/mcp_config.json

mcp_config.json

{
  "mcpServers": {
    "nomik": {
      "command": "npx",
      "args": ["-y", "@nomik-ai/cli", "mcp"],
      "env": {
        "NOMIK_GRAPH_URI": "bolt://localhost:7687",
        "NOMIK_GRAPH_USER": "neo4j",
        "NOMIK_GRAPH_PASS": "nomik_local",
        "NOMIK_PROJECT_ID": "my-api"
      }
    }
  }
}

After restarting Windsurf, Nomik tools are available in Cascade (Windsurf's AI assistant).

Claude Desktop

Terminal

$ nomik setup-claude

✓ Created Claude Desktop MCP config
  Server:  @nomik-ai/cli (stdio)
  Neo4j:   bolt://localhost:7687
  Project: my-api

Restart Claude Desktop to activate.

Config file locations:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

{
  "mcpServers": {
    "nomik": {
      "command": "npx",
      "args": ["-y", "@nomik-ai/cli", "mcp"],
      "env": {
        "NOMIK_GRAPH_URI": "bolt://localhost:7687",
        "NOMIK_GRAPH_USER": "neo4j",
        "NOMIK_GRAPH_PASS": "nomik_local",
        "NOMIK_PROJECT_ID": "my-api"
      }
    }
  }
}

After restarting Claude Desktop, use the MCP tools icon (hammer) to verify the connection.

Antigravity

Terminal

$ nomik setup-antigravity

✓ Created Antigravity MCP config
  Server:  @nomik-ai/cli (stdio)
  Neo4j:   bolt://localhost:7687
  Project: my-api

Restart Antigravity to activate.

Creates the platform-specific mcp_config.json for Antigravity Editor.

Verifying the Connection

After setting up any editor:

Step 1: Run diagnostics from the terminal:

Terminal

$ nomik doctor

✓ Node.js:      v22.4.0 (>= 20 required)
✓ Neo4j:        Connected (5.18.0 Community)
✓ Project:      my-api (.nomik/project.json)
✓ MCP Server:   dist/mcp-server.js (found)
✓ Cursor:       .cursor/mcp.json (configured)

Step 2: Ask your AI assistant:

"What MCP tools do you have access to?"

You should see 21 Nomik tools listed: nm_search, nm_explain, nm_impact, nm_trace, nm_path, nm_context, nm_health, nm_db_impact, nm_changes, nm_projects, nm_communities, nm_flows, nm_diff, nm_guard, nm_rules, nm_rename, nm_wiki, nm_service_links, nm_test_impact, nm_audit, nm_onboard.

Step 3: Try a real query:

"Give me a codebase briefing"

The AI should call nm_onboard and return your codebase stats, language distribution, DB tables, external APIs, and high-risk functions.

Troubleshooting

Issue	Solution
Tools don't appear after restart	Check `nomik doctor` — verify Neo4j is running and config file exists
"Connection refused" errors	Make sure Neo4j is running: `docker compose up -d`
Wrong project data	Check `NOMIK_PROJECT_ID` in the config matches your scanned project: `nomik project list`
Stale data after code changes	Re-scan: `nomik scan .` or use `nomik watch .` for live updates
Permission denied on config file	Ensure write permissions to the config file location

Transport Modes

Transport	Use Case	Setup
stdio (default)	Local editors (Cursor, Windsurf, Claude Desktop, Antigravity)	Automatic via `nomik setup-*` commands
SSE	Remote access, web dashboards	`nomik serve` — MCP on port 3334
Streamable HTTP	Production, multi-client environments	Custom deployment

For local development, stdio is all you need — the editor launches the MCP server on demand.

Role-Scoped Access

You can limit what tools the AI sees by setting NOMIK_ROLE in the config:

Restrict to architecture tools only

{
  "env": {
    "NOMIK_ROLE": "architect"
  }
}

Role	Use Case	Available Tools
`dev` (default)	Full access	All 21 tools, 9 resources, 6 prompts
`architect`	Architecture review	rules, communities, flows, diff, onboard, guard
`security`	Security audit	audit, guard, rules, health
`pm`	Project management	onboard, changes, changelog, health, wiki

On this page