mindgraph-mcp

Model Context Protocol server for MindGraph — plug your persistent, structured knowledge graph into Claude Desktop, Claude Code, and any MCP-compatible client.

Install

The fastest way to install is the interactive setup:

npx mindgraph-mcp init

This walks you through:

1. Sign in via browser (or paste an existing API key).
2. Pick your client — Claude Desktop, Claude Code, or both.
3. The server is wired up automatically; restart your client to activate.

Don't have a MindGraph account yet? Sign up at mindgraph.cloud first.

Manual install

# Claude Desktop
npx mindgraph-mcp install --api-key mg_your_key_here

# Claude Code
npx mindgraph-mcp install-code --api-key mg_your_key_here

Or drop this into your Claude Desktop config by hand (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mindgraph": {
      "command": "npx",
      "args": ["-y", "mindgraph-mcp@latest"],
      "env": {
        "MINDGRAPH_API_KEY": "mg_your_key_here"
      }
    }
  }
}

What You Get

7 tools covering the full knowledge-graph workflow:

| Tool | Purpose | |------|---------| | mindgraph_capture | Entities, observations, sources, snippets, concepts, journal entries | | mindgraph_reason | Claims with evidence, open questions, hypotheses, theories, anomalies | | mindgraph_commit | Goals, projects, decisions, options, milestones | | mindgraph_plan | Plans, tasks, procedures, governance policies, risk assessments, executions | | mindgraph_retrieve | BM25 / semantic / hybrid search, traversal (chain, neighborhood, path, subgraph), document index | | mindgraph_ingest | Chunk / document / session ingestion with LLM-powered extraction | | mindgraph_synthesize | Project-scoped cross-document synthesis — mine signals, spawn Article-generation jobs |

7 prompt templates for common workflows:

graph-summary, active-goals, open-questions, review-contradictions, knowledge-about, daily-briefing, capture-conversation.

Resources (static + dynamic URIs):

• mindgraph://stats, mindgraph://goals, mindgraph://questions, mindgraph://contradictions, mindgraph://decisions
• mindgraph://node/{uid} — a node with all its outgoing and incoming edges
• mindgraph://search/{query} — BM25 search results
• mindgraph://layer/{layer} — all nodes in a cognitive layer (reality, epistemic, intent, action, memory, agent)

CLI

mindgraph-mcp                  Start the MCP server (stdio transport)
mindgraph-mcp init             Interactive setup
mindgraph-mcp install          Install into Claude Desktop config
mindgraph-mcp install-code     Install into Claude Code
mindgraph-mcp uninstall        Remove from Claude Desktop config
mindgraph-mcp uninstall-code   Remove from Claude Code
mindgraph-mcp status           Show installation status

Options: --api-key <key>, --base-url <url>, --help.

Environment

| Variable | Default | Purpose | |----------|---------|---------| | MINDGRAPH_API_KEY | (required) | Your MindGraph API key (mg_…) | | MINDGRAPH_BASE_URL | https://api.mindgraph.cloud | Override for self-hosted deployments | | MINDGRAPH_AGENT_ID | mcp | Stamped onto every node/edge written by the MCP — useful for provenance across multiple agents | | MINDGRAPH_ORG_ID | (unset) | Pin operations to a specific organization when a key has access to more than one |

Usage in Claude

Once installed, start asking Claude about your knowledge graph naturally:

"What did I capture about climate policy last week?" "Summarize my active goals and open decisions." "Ingest this PDF and extract the main claims." "Find entities mentioned across multiple project documents, then spin up a synthesis."

The server auto-injects agent_id: "mcp" on every write so you always know which nodes came from your MCP sessions.

Architecture

This MCP server is a thin wrapper over the mindgraph TypeScript SDK. It exposes cognitive-layer abstractions (Reality, Epistemic, Intent, Action, Memory, Agent) as consolidated tools rather than one-tool-per-endpoint, which keeps the tool surface compact enough for high-quality tool selection by the model.

Search strategy is keyword-first: mindgraph_retrieve defaults to action: "context" which uses BM25. Escalate to semantic or hybrid only when keywords fail.

Development

git clone https://github.com/shuruheel/mindgraph-mcp
cd mindgraph-mcp
npm install
npm run build            # build with tsup (CJS + .d.ts)
npm run lint             # tsc --noEmit
npm run dev              # tsup --watch

License

MIT