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

Related MCP server: MyChatArchive MCP Server

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:

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

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

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

Org chart walkthrough

The examples/ folder has a made-up 40-person company to try the org tools on:

• northwind-jan.csv: the January team as id,name,title,manager,kind,email

• northwind-mindmap.json: the same company after a year of changes (hires, leavers, a reorg, title changes, three projects with people linked to them), with the dated history, built by build-sample.mjs through the server's own tools

To start from the finished sample, copy it over your map first (back yours up: it replaces ~/.mindkeeper/mindmap.json). Or start from the CSV and ask your assistant, one prompt at a time:

1. "Import examples/northwind-jan.csv as our org chart, effective 2026-01-05." → import_csv filePath="examples/northwind-jan.csv" effectiveDate="2026-01-05" (managers by CSV id, everyone is a person)

2. "Add a project Atlas API under Daniel Okafor; Priya leads it and Liam works on it." → add_entity name="Atlas API" kind="project" parentId=<Daniel>, then link_entities from=<Priya> to=<Atlas> type="leads" and type="works on"

3. "Ben Carter left on 31 March. Tariq Aziz joined Sofia's team on 2 March as ML Engineer." → delete_node nodeId=<Ben> effectiveDate="2026-03-31", add_entity name="Tariq Aziz" kind="person" parentId=<Sofia> attrs={"title":"ML Engineer"} effectiveDate="2026-03-02"

4. "From 1 June, Sofia reports to Maya as VP Data, and Support moves under Laura." → move_node nodeId=<Sofia> newParentId=<Maya> effectiveDate="2026-06-01", add_entity with the same name and parent to set attrs.title, move_node nodeId=<Fatima> newParentId=<Laura>

5. "Who reports to Daniel, all the way down?" → reports_of personId=<Daniel> all=true

6. "Which projects is Daniel's org on?" → projects_of entityId=<Daniel> includeReports=true

7. "Who's on Customer insights?" → members_of groupId=<Customer insights> (people under it and people linked to it)

8. "What did the org look like on 31 January?" → snapshot_as_of date="2026-01-31"

9. "What changed between January and July?" → diff_between dateA="2026-01-31" dateB="2026-07-31": joined, left, moved (old and new manager), changed fields, links added and removed

10. "Give me the org chart." → export_orgchart (Mermaid flowchart TB to paste into GitHub/Notion, plus JSON for mindkeeper-map.js) or export_html for an interactive page

11. "Export it as CSV so I can edit it in a spreadsheet." → export_csv; edit, then import_csv the file again: rows whose id is an existing node update it, and the moves and title changes land in the history

To see the same company drawn in the browser, with the January vs July diff highlighted, open the org chart and reorg samples of mindkeeper-js.

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:

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.