mindkeeper-mcp

An MCP server that captures ideas from conversations and organises them into a persistent mindmap — and keeps org charts: people, teams, companies and projects, how they are linked, and how that changed over time. 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
• Org charts — typed entities (person, company, team, role, project), cross-links for many-to-many relations, re-parenting, and who-reports-to-whom queries
• Change history — every edit is logged with an optional effective date, so you can see the chart as of any day and diff two dates
• CSV in and out — import an org chart from a spreadsheet (id,name,title,manager,kind), export it back, or export Mermaid / mindkeeper-map JSON

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
add_entity	Add a typed entity (person, company, team, role, project, idea) with attributes such as title or email
link_entities	Record a relation outside the tree, e.g. a person works_on a project
unlink_entities	Remove a relation
move_node	Re-parent a node and its subtree (new manager, new team); refuses cycles
get_history	Recorded changes, newest first, with before/after values and effective dates
snapshot_as_of	The map or org chart as it stood on a date

Every write tool (add_idea, update_node, delete_node, add_entity, link_entities, unlink_entities, move_node, import_csv) also takes an optional effectiveDate (YYYY-MM-DD or ISO) for changes that happened earlier than today.

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"]

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗