Claude Desktop setup

commitmind init auto-installs the MCP server entry into Claude Desktop's config when it detects the app is installed. This page is for when you want to wire it up by hand — for a second machine, a teammate's config, or a workspace where you skipped the wiring prompt.

Heads up. This page is for Claude Desktop — the macOS / Windows / Linux native app. If you're using Claude Code (the claude CLI), see Claude Code setup instead. The two products are independent and read MCP config from different files.

MCP config

Claude Desktop reads its MCP server list from a JSON config file:

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

This file is global — every Claude Desktop session uses the same MCP server list, regardless of which folder you're working in. CommitMind's MCP server resolves the per-repo agent token from ~/.config/commitmind/tokens/<repo_hash>.json based on the process's current directory, so a single global entry works correctly across every repo you've run commitmind init in.

Add a commitmind entry under mcpServers. The exact block commitmind init writes:

{
  "mcpServers": {
    "commitmind": {
      "command": "commitmind",
      "args": ["mcp", "serve"]
    }
  }
}

That's it — no env vars to manage in the common case.

If you point CommitMind at a non-default backend, add the env block:

{
  "mcpServers": {
    "commitmind": {
      "command": "commitmind",
      "args": ["mcp", "serve"],
      "env": {
        "COMMITMIND_BACKEND_URL": "https://api.commitmind.dev"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Tools

CommitMind exposes the same tool surface in Claude Desktop that it does in Claude Code — prime_session, search_memory, log_observation, promote_decision, the task_* family, the symbol-level code-intel tools, the project-rules surface, and the learnings surface.

See the Claude Code page for the full per-tool reference; the behaviour is identical regardless of which client spawned the MCP server.

Troubleshooting

MCP server not connecting

Run through the checklist:

Agent token present. commitmind status should show a logged-in user and a linked project. If not, re-run commitmind init from inside the repo.
Backend URL reachable. curl https://api.commitmind.dev/healthz from the machine where Claude Desktop runs. Corp VPNs occasionally block it.
Claude Desktop restarted. MCP config is read on startup — quit and relaunch after any edit.
Logs. Claude Desktop writes MCP logs to:
- macOS: ~/Library/Logs/Claude/mcp*.log
- Linux: ~/.local/state/Claude/logs/mcp*.log
- Windows: %LOCALAPPDATA%\Claude\logs\mcp*.log
Grep for commitmind — transport-level errors surface there first.

The `commitmind` binary isn't found

Claude Desktop inherits your login shell's $PATH. If commitmind works in your terminal but not from Claude Desktop, point the MCP config at an absolute path:

{
  "mcpServers": {
    "commitmind": {
      "command": "/Users/you/go/bin/commitmind",
      "args": ["mcp", "serve"]
    }
  }
}

Wrong project loaded

Claude Desktop is a global app — it doesn't know which "project" you're working on. CommitMind picks the active project by walking up from the process's current directory to find a .git/ directory and then hashing the git remote. If you launch Claude Desktop and it loads tools for the "wrong" repo, check that the working directory it spawns the MCP server in matches the repo you ran commitmind init for.

For repo-aware MCP routing, prefer Claude Code — its per-project .mcp.json removes the ambiguity entirely.