Mind Elixir MCP Server

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/mcp and streams the results back.

• Registry name: io.github.mind-elixir/mcp
• npm package: @mind-elixir/mcp
• Setup guide: https://app.mind-elixir.com/blog/use-mcp

Contents

• What you can do with it
• Requirements
• Quick start
• Client configuration
• Connecting without the bridge (HTTP)
• Tools reference
• Recommended agent workflow
• CLI reference
• How it works
• Troubleshooting
• Security and privacy
• Development
• License

What you can do with it

Seven tools let an assistant read and mutate the mind map that is currently open in the app:

• Start a fresh map, or replace the current one with a structure the model designed.
• Inspect every topic, node ID, and parent/child relationship in the current map.
• Rename nodes, add child nodes, and get back the ID of what was just created.
• Attach summary nodes that collapse a range of siblings into one idea.
• Draw labelled arrows between any two nodes to express relationships that the tree cannot.

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.

Requirements

Quick start

Start Mind Elixir Desktop first, then verify the bridge can reach it:

npx -y @mind-elixir/mcp@latest

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:

npm install -g @mind-elixir/mcp
mind-elixir-mcp

Then configure your MCP client — see the next section.

Client configuration

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mind-elixir": {
      "command": "npx",
      "args": ["-y", "@mind-elixir/mcp@latest"]
    }
  }
}

Restart Claude Desktop after saving.

Claude Code

claude mcp add mind-elixir -- npx -y @mind-elixir/mcp@latest

Cursor

Create or edit ~/.cursor/mcp.json (or use Settings → Features → MCP → + Add New MCP Server):

{
  "mcpServers": {
    "mind-elixir": {
      "command": "npx",
      "args": ["-y", "@mind-elixir/mcp@latest"]
    }
  }
}

VS Code (GitHub Copilot agent mode)

Add to .vscode/mcp.json in your workspace, or to your user-level mcp.json:

{
  "servers": {
    "mind-elixir": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mind-elixir/mcp@latest"]
    }
  }
}

Cline, Roo Code, Windsurf

These extensions share the mcpServers shape used by Cursor:

{
  "mcpServers": {
    "mind-elixir": {
      "command": "npx",
      "args": ["-y", "@mind-elixir/mcp@latest"]
    }
  }
}

Non-default port

If Mind Elixir Desktop is listening somewhere other than 6595, pass the port through:

{
  "mcpServers": {
    "mind-elixir": {
      "command": "npx",
      "args": ["-y", "@mind-elixir/mcp@latest", "--port", "7000"]
    }
  }
}

Connecting without the bridge (HTTP)

If your client can talk Streamable HTTP directly, skip this package entirely and point it at the app:

{
  "mcpServers": {
    "mind-elixir": {
      "type": "http",
      "url": "http://127.0.0.1:6595/mcp"
    }
  }
}

The app exposes:

CORS is enabled for the Mind Elixir Cloud origin, so browser-hosted clients can call the local server too.

Tools reference

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:.

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_mindmap

Creates a new, empty mind map and navigates the app to its editor page.

No parameters.

get_all_nodes

Returns the current map as a nested node tree — every topic, its ID, and its children.

No parameters. Shape of the response:

{
  "topic": "Root Topic",
  "id": "1",
  "children": [
    { "topic": "Child Topic", "id": "b3f1c0e2-…", "children": [] }
  ]
}

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_mindmap

Replaces the entire current map with the structure you supply.

{
  "nodeData": {
    "topic": "Root Topic",
    "id": "1",
    "children": [
      { "topic": "Child Topic 1", "id": "1-1", "children": [] },
      { "topic": "Child Topic 2", "id": "1-2" }
    ]
  }
}

Requirements:

• Every node needs topic (string) and id (string).
• children is optional.
• Use hierarchical numbering (1, 1-1, 1-2, 2, 2-1, …) so later tools can address nodes predictably.

edit_topic

Changes a node's text in place, preserving its position, children, summaries, and arrows.

Returns Error: Node not found if node_id does not exist — call get_all_nodes to refresh your view.

add_child

Adds a child node under an existing parent. The app generates the ID, so the result carries it.

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_summary

Attaches a summary node that consolidates a contiguous range of a parent's children.

Example — summarise the first three children of node 1:

{ "text": "These three all concern onboarding", "parent": "1", "start": 0, "end": 2 }

add_arrow

Draws a labelled connection between two nodes, for relationships the tree cannot express.

Recommended agent workflow

1. Orient first. Call get_all_nodes to learn the real IDs and structure before touching anything. Never assume an ID.
2. Decide between build and patch. For a brand-new map use generate_mindmap with hierarchical IDs. For incremental work on an existing map use add_child and edit_topic.
3. Capture generated IDs. add_child returns a UUID — record it if the node will be edited again.
4. Do not rely on the app being on the editor page. Any tool call brings the app to the front and opens the editor; if it was not already editing a map, a new blank map is created first. So always confirm the current state with get_all_nodes before a write.
5. Keep calls sequential. Mutations are applied in order, and there is no undo exposed over MCP.

CLI reference

USAGE:
  npx -y @mind-elixir/mcp [options]

OPTIONS:
  -u, --url <url>            Target Mind Elixir MCP URL (default: http://127.0.0.1:6595/mcp)
  -p, --port <port>          Change target port (default: 6595)
  -t, --transport <sse|http> Force transport mode ('sse' or 'http', default: auto)
  -v, --version              Show version
  -h, --help                 Show this help message

ENVIRONMENT VARIABLES:
  MIND_ELIXIR_MCP_URL        Target URL to connect to

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.

How it works

+--------------------------+
| Claude Desktop / Cursor  |
+------------+-------------+
             | stdio (stdin / stdout), JSON-RPC
             v
+------------+-------------+
|    @mind-elixir/mcp      |   bridge process
+------------+-------------+
             | Streamable HTTP -> http://127.0.0.1:6595/mcp
             v
+------------+-------------+
|  Mind Elixir Desktop     |   Tauri app, owns the tools
+--------------------------+

1. The bridge translates stdio JSON-RPC messages into HTTP requests and streams responses back verbatim.
2. Startup is tolerant. If the app is still booting, messages are buffered and replayed in strict FIFO order once the connection is established. The bridge retries the connection three times, one second apart.
3. Protocol version is negotiated. The bridge starts at 2024-11-05 and adopts whatever version the initialize handshake settles on, forwarding it to the app.
4. Failures are explicit. If the app never becomes reachable, every buffered request receives a JSON-RPC error (-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.

Troubleshooting

Security and privacy

• The app's MCP server binds 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.
• The bridge is a local child process of your MCP client. It reads and writes nothing on disk; the only network traffic is the loopback HTTP call to the app.
• Everything happens on your machine. No mind map content, prompt, or telemetry is sent to a server by this package or by the desktop app's MCP endpoint.
• Grant the server the same care you would give any tool that edits your documents: it can rewrite the map you have open. Prefer clients configured to ask before running tools when you are working on something important.

Development

Requires Node.js 18+ and pnpm 11+ (the allowBuilds entry in pnpm-workspace.yaml depends on it).

pnpm install
pnpm build     # tsup -> dist/index.js
pnpm dev       # tsup --watch

The build emits a single bundled ESM file with a #!/usr/bin/env node shebang; prepublishOnly rebuilds before every npm publish.

License

MIT © Mind Elixir