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
• Safe writes — atomic temp-file → backup → rename strategy
• Concurrency-safe — serialised write queue prevents file corruption
• Export — Markdown, Mermaid diagram, OPML, JSON, or interactive HTML (with PNG/SVG download)
• Import — build a mindmap from your Claude.ai conversation history
• 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. The quickest way to open it: in Claude Desktop, go to Settings → Developer → Edit Config.

Alternatively, find the file at:

| 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.
- 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 | | 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 | | export_html | Generate a self-contained interactive HTML file saved to ~/.mindkeeper/mindmap-export.html — open in browser, drag, zoom, export PNG or SVG | | import_claude_export | Parse a conversations.json from Claude.ai's data export and build a mindmap from your conversation history | | 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

Export for a document:

export_markdown

Visualize interactively:

export_html   # opens in browser — drag, zoom, download PNG or SVG from the toolbar

Or paste into an online renderer:

export_json   # drop the output into the visualizer at the project website

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.

Import from Claude.ai

Turn your entire Claude.ai conversation history into a structured mindmap in three steps.

Step 1 — Export your Claude.ai data

1. Open claude.ai and go to Settings → Account
2. Scroll to Export Data and click Export
3. Claude emails you a download link within a few minutes
4. Download the ZIP and unzip it — find conversations.json inside

Step 2 — Import and build the mindmap

Tell Claude:

Import my Claude export from /path/to/conversations.json into my mindmap

Replace the path with the actual location:

• Windows: C:\Users\YourName\Downloads\claude-export\conversations.json
• Mac/Linux: /Users/YourName/Downloads/claude-export/conversations.json

Claude reads every conversation, clusters them by theme, and populates the mindmap. Trivial or very short conversations are skipped automatically.

Step 3 — Visualise the result

Export the mindmap as HTML

The HTML file is saved to ~/.mindkeeper/mindmap-export.html and opens in any browser — no server needed. Inside the file, use the toolbar buttons to download a PNG or SVG image.

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.

License & Credits

MIT License — see LICENSE.

Open-source dependencies:

| Package | License | Used for | |---|---|---| | @modelcontextprotocol/sdk | MIT | MCP server protocol | | uuid | MIT | Node ID generation | | D3.js | ISC | Force graph & tree views in the web visualizer |

Original work:

mindkeeper-map.js — the interactive mindmap renderer used in the exported HTML and web visualizer is original code with no external dependencies. Algorithms: slot-based tree layout, cubic-bezier links, canvas measureText node sizing, per-node drag coexisting with canvas pan.