mindkeeper-mcp

An MCP server that captures ideas from conversations and organises them into a persistent mindmap. Ideas are stored as nodes that can be linked to a parent, tagged, searched, exported, and synced to the cloud — surviving across sessions.

Data is stored in ~/.mindkeeper/mindmap.json with atomic writes and automatic backups.

Features

• Persistent — mindmap survives across conversations and restarts
• Hierarchical — nest ideas under parents to build tree structure
• Searchable — weighted full-text search across text and tags
• Deduplication — same idea under the same parent is never added twice
• Session resume — recall what was last discussed at the start of any conversation
• Safe writes — atomic temp-file → backup → rename strategy
• Concurrency-safe — serialised write queue prevents file corruption
• Export — Markdown, Mermaid diagram, OPML, or raw JSON
• Cloud sync — backup and restore via private GitHub Gist

Installation

Global install (recommended)

npm install -g mindkeeper-mcp

Local install

git clone https://github.com/icedsg/mindkeeper-mcp
cd mindkeeper-mcp
npm install
npm run build

Configuration

Claude Desktop

Edit claude_desktop_config.json:

| Platform | Location | |---|---| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/claude/claude_desktop_config.json |

Global install:

{
  "mcpServers": {
    "mindkeeper": {
      "command": "mindkeeper-mcp"
    }
  }
}

Local install (absolute path):

{
  "mcpServers": {
    "mindkeeper": {
      "command": "node",
      "args": ["/absolute/path/to/mindkeeper-mcp/build/index.js"]
    }
  }
}

After editing the config, restart Claude Desktop for the server to connect.

Claude Code (CLI)

# Global install
claude mcp add mindkeeper -- mindkeeper-mcp

# Local install
claude mcp add mindkeeper -- node /path/to/mindkeeper-mcp/build/index.js

Automatic topic capture (recommended)

Add this to your Claude Desktop system prompt (Settings → Profile → Custom Instructions) to make mindkeeper capture your topics automatically:

You have mindkeeper-mcp connected.
- At the start of every conversation, call get_last_session and briefly say what was last on my mind.
- After each of my messages, if I mention a new topic, question, goal, or interest — call add_idea to record it. Only capture what I say, never your own responses.
- Before adding, call search_ideas to avoid duplicates.

Tools

| Tool | Description | |---|---| | add_idea | Capture a new idea, optionally attached to a parent node | | update_node | Edit the text or tags of an existing idea | | delete_node | Remove an idea; children are orphaned (kept, not deleted) | | search_ideas | Full-text search across idea text and tags | | get_mindmap | Retrieve the full tree, or a subtree from a given node | | get_last_session | Return the most recently touched nodes — use at conversation start to resume context | | export_markdown | Export as a nested Markdown list | | export_mermaid | Export as a Mermaid flowchart — paste into GitHub, Notion, or Obsidian | | export_opml | Export as OPML — import into MindNode, OmniOutliner, or XMind | | export_json | Export raw JSON — use with the online visualizer | | sync_cloud | Push or pull the mindmap to/from a private GitHub Gist | | cloud_status | Show current cloud sync configuration |

Usage examples

Capture a top-level idea:

add_idea  text="Product strategy for Q3"  tags=["strategy","q3"]

Add a sub-idea under an existing node:

add_idea  text="Launch in EU market"  parentId="<id from previous call>"  tags=["launch"]

Refine an idea:

update_node  nodeId="<id>"  newText="Launch in EU market — target Germany first"

Find related ideas:

search_ideas  query="EU launch"

See the whole map:

get_mindmap

Resume where you left off:

get_last_session

Export for a document:

export_markdown

Visualize in the browser:

export_json   # copy the output, drop it into the visualizer

Cloud sync

Create ~/.mindkeeper/config.json:

{
  "cloud": {
    "provider": "github_gist",
    "token": "ghp_YOUR_PERSONAL_ACCESS_TOKEN"
  }
}

Generate a token at github.com/settings/tokens with the gist scope. The first sync_cloud direction="push" auto-creates a private Gist and saves the gistId back to config.

Visualizer

Export your mindmap as JSON and drop it into the browser-based visualizer at icedsg.github.io/mindkeeper-mcp/visualize.html for zoomable, draggable, multi-layout exploration.

Data storage

The mindmap is stored in ~/.mindkeeper/mindmap.json. A backup is kept at ~/.mindkeeper/mindmap.json.bak and is overwritten on every save.

To reset: delete or rename mindmap.json. The server creates a fresh empty map on next use.

Development

npm run dev    # tsx watch mode — restarts on file change
npm run build  # compile TypeScript to ./build
npm test       # run test suite (requires bash)

Troubleshooting

Server not found after global install

Ensure npm's global bin directory is on your PATH:

npm config get prefix   # e.g. /usr/local
# Add /usr/local/bin to PATH if missing

Permission denied on ~/.mindkeeper

mkdir -p ~/.mindkeeper
chmod 755 ~/.mindkeeper

Mindmap is empty after restart

Check the file exists and is valid JSON:

cat ~/.mindkeeper/mindmap.json | node -e "process.stdin.resume(); let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>console.log(JSON.parse(d).rootId))"

If the file is corrupt, restore from backup:

cp ~/.mindkeeper/mindmap.json.bak ~/.mindkeeper/mindmap.json

stdio errors in Claude Desktop logs

The server logs all operations to stderr (visible in Claude Desktop's MCP logs). Normal log lines start with [mindkeeper]. Anything else is an unexpected error.