# 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)

```bash
npm install -g mindkeeper-mcp
```

### Local install

```bash
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:**

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

**Local install (absolute path):**

```json
{
  "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)

```bash
# 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](https://icedsg.github.io/mindkeeper-mcp/visualize.html) |
| `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 |
| `diff_between` | Who joined, left, moved or was renamed between two dates, plus links added/removed |
| `projects_of` | Projects a person, team or company is on (tree or links) |
| `members_of` | People in a project, company or team |
| `reports_of` | A person's manager and direct (or all) reports |
| `export_orgchart` | Org chart as a Mermaid flowchart TB and mindkeeper-map JSON (with links) |
| `export_csv` | CSV: id,name,title,manager,kind plus other attributes |
| `import_csv` | Build or update an org chart from a CSV; edits land in the history |

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/`](examples) folder has a made-up 40-person company to try the org tools on:

- [`northwind-jan.csv`](examples/northwind-jan.csv): the January team as `id,name,title,manager,kind,email`
- [`northwind-mindmap.json`](examples/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`](examples/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](https://github.com/icedsg/mindkeeper-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](https://icedsg.github.io/mindkeeper-js/orgchart.html) and
[reorg](https://icedsg.github.io/mindkeeper-js/reorg.html) samples of mindkeeper-js.

## Cloud sync

Create `~/.mindkeeper/config.json`:

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

Generate a token at [github.com/settings/tokens](https://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](https://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](https://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

```bash
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`:
```bash
npm config get prefix   # e.g. /usr/local
# Add /usr/local/bin to PATH if missing
```

**Permission denied on `~/.mindkeeper`**

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

**Mindmap is empty after restart**

Check the file exists and is valid JSON:
```bash
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:
```bash
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](LICENSE).

**Open-source dependencies:**

| Package | License | Used for |
|---|---|---|
| [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) | MIT | MCP server protocol |
| [uuid](https://github.com/uuidjs/uuid) | MIT | Node ID generation |
| [D3.js](https://d3js.org) | ISC | Force graph & tree views in the web visualizer |

**Original work:**

[`mindkeeper-map.js`](docs/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.