The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Mind Elixir listing page.
Let AI assistants build and edit real mind maps in Mind Elixir Desktop.
This is the stdio ↔ HTTP bridge that connects stdio-only MCP clients — Claude Desktop, Claude Code, Cursor, VS Code, Cline, Roo Code, Windsurf — to the MCP server built into the Mind Elixir Desktop app.
Requires Mind Elixir Desktop to be installed and running. This server is a local controller for the desktop app, not a standalone cloud service. The bridge forwards tool calls to
http://127.0.0.1:6595/mcpand streams the results back.
io.github.mind-elixir/mcp@mind-elixir/mcpSeven tools let an assistant read and mutate the mind map that is currently open in the app:
Typical uses: turning a conversation or a document into a structured map, breaking a project down into a work breakdown structure, summarising a meeting into themes, or having an assistant reorganise notes you already made by hand.
| Requirement | Detail |
|---|---|
| Mind Elixir Desktop | Installed and running. The app hosts the actual MCP server on 127.0.0.1:6595. |
| Node.js | 18 or newer — only needed to run the bridge via npx, npm i -g, or a local install. |
| MCP client | Any client that speaks MCP over stdio, or one that can connect directly to a Streamable HTTP endpoint. |
| Port | 6595 must be free on loopback. Override with --port if it is not. |
Start Mind Elixir Desktop first, then verify the bridge can reach it:
A running bridge prints nothing to stdout (that channel is reserved for JSON-RPC) and stays in the foreground. Diagnostics go to stderr. Quit it with Ctrl+C.
To install the CLI globally instead:
Then configure your MCP client — see the next section.
Edit claude_desktop_config.json:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonRestart Claude Desktop after saving.
Create or edit ~/.cursor/mcp.json (or use Settings → Features → MCP → + Add New MCP Server):
Add to .vscode/mcp.json in your workspace, or to your user-level mcp.json:
These extensions share the mcpServers shape used by Cursor:
If Mind Elixir Desktop is listening somewhere other than 6595, pass the port through:
If your client can talk Streamable HTTP directly, skip this package entirely and point it at the app:
The app exposes:
| Endpoint | Method | Purpose |
|---|---|---|
/mcp | POST / GET | MCP Streamable HTTP endpoint (the one you want). |
/ping | GET | Liveness probe; returns pong. |
CORS is enabled for the Mind Elixir Cloud origin, so browser-hosted clients can call the local server too.
All tools return a plain-text result. Successful mutations answer with OK (or, for add_child, the new node's ID); failures come back as a string beginning with Error:.
| Tool | Purpose | Returns |
|---|---|---|
new_mindmap | Create a blank map and switch the app to the editor | OK |
get_all_nodes | Read the whole current map | Node tree JSON |
generate_mindmap | Replace the current map from structured data | OK |
edit_topic | Rename a node | OK |
add_child | Add a child node | Done. New Node's ID is <id>. |
add_node_summary | Summarise a range of siblings | OK |
add_arrow | Connect two nodes with a labelled arrow | OK |
Every tool has a 15-second operation budget. If the app does not report back in time, the tool returns Timeout waiting for mindmap operation to complete.
new_mindmapCreates a new, empty mind map and navigates the app to its editor page.
No parameters.
get_all_nodesReturns the current map as a nested node tree — every topic, its ID, and its children.
No parameters. Shape of the response:
Always call this before editing or adding to a map you did not create in this session — IDs are the only way to address nodes.
generate_mindmapReplaces the entire current map with the structure you supply.
| Parameter | Type | Description |
|---|---|---|
mindmap_data | string | A JSON string with a nodeData root object. |
Requirements:
topic (string) and id (string).children is optional.1, 1-1, 1-2, 2, 2-1, …) so later tools can address nodes predictably.edit_topicChanges a node's text in place, preserving its position, children, summaries, and arrows.
| Parameter | Type | Description |
|---|---|---|
node_id | string | ID of the node to rename, e.g. 1, 1-1, or a UUID. |
topic | string | The new topic text. |
Returns Error: Node not found if node_id does not exist — call get_all_nodes to refresh your view.
add_childAdds a child node under an existing parent. The app generates the ID, so the result carries it.
| Parameter | Type | Description |
|---|---|---|
parent_id | string | ID of the parent node. |
topic | string | Topic text for the new child. |
Returns Done. New Node's ID is <id>. — keep that ID if you plan to edit the node later. Returns Error: Parent node not found when the parent is missing.
add_node_summaryAttaches a summary node that consolidates a contiguous range of a parent's children.
| Parameter | Type | Description |
|---|---|---|
text | string | The summary text. |
parent | string | ID of the parent whose children are being summarised. |
start | integer | Zero-based index of the first child to include. |
end | integer | Zero-based index of the last child to include (inclusive). |
Example — summarise the first three children of node 1:
add_arrowDraws a labelled connection between two nodes, for relationships the tree cannot express.
| Parameter | Type | Description |
|---|---|---|
label | string | Text shown on or near the arrow, e.g. leads to, depends on. |
from | string | ID of the source node. |
to | string | ID of the target node. |
bidirectional | boolean | true for ↔, false for →. |
get_all_nodes to learn the real IDs and structure before touching anything. Never assume an ID.generate_mindmap with hierarchical IDs. For incremental work on an existing map use add_child and edit_topic.add_child returns a UUID — record it if the node will be edited again.get_all_nodes before a write.The package installs two equivalent binaries: mind-elixir-mcp and mcp.
Transport selection in auto mode: if the target URL path ends with /mcp, Streamable HTTP is used; otherwise the bridge falls back to the legacy SSE transport. Force one with --transport.
2024-11-05 and adopts whatever version the initialize handshake settles on, forwarding it to the app.-32000) reading Mind Elixir Desktop is not running. Please open Mind Elixir Desktop and try again. (<url>), stderr gets a human-readable explanation, and the process exits with code 1. Errors raised during an operation are returned to the caller as their original message rather than being swallowed.| Symptom | Cause and fix |
|---|---|
Mind Elixir Desktop is not running | Launch the desktop app, then reconnect the MCP server in your client. |
Tool call returns Timeout waiting for mindmap operation to complete | The app did not respond within 15 s — usually a modal dialog or a busy window. Bring the app to the front and retry. |
Connection refused on 6595 | The port is taken by another process, or the app is on a different port. Restart the app, or pass --port <port> / set MIND_ELIXIR_MCP_URL. |
| The client lists no tools | Confirm the bridge starts by running npx -y @mind-elixir/mcp@latest in a terminal, then restart the client so it re-reads its MCP config. |
| A blank map appeared unexpectedly | The app was not on an editor page when a tool ran, so it created one. Read the map with get_all_nodes before writing. |
Error: Node not found / Error: Parent node not found | The ID is stale or comes from a different map. Re-read with get_all_nodes. |
| Nothing appears in the client's log | All bridge diagnostics go to stderr; stdout carries protocol traffic only. |
127.0.0.1 only — it is never exposed to your network, and it has no authentication. Any local process on your machine can drive the app through it, so treat port 6595 like any other local control surface.Requires Node.js 18+ and pnpm 11+ (the allowBuilds entry in pnpm-workspace.yaml depends on it).
The build emits a single bundled ESM file with a #!/usr/bin/env node shebang; prepublishOnly rebuilds before every npm publish.
MIT © Mind Elixir