Let your AI agents build mindmaps with mindmap.io MCP

Your agent can research a topic, reason through it, and write up an answer, but the moment the run ends that structure is gone. The next session starts from an empty context, and the person who asked is left with a wall of text instead of something they can navigate.

Install the mindmap.io agent surface and your agent gets a place to put that work. It builds a real map as it goes: a root topic, child questions, answers under each one, branches it can grow on demand. The map persists, opens in a browser, and is shareable, so the thinking outlives the run.

This works because mindmap.io is built around a node API where every node can hold a live AI conversation. Your agent drives the same primitives a person does in the app: create a map, hang nodes off it, run a node through a model, fan a node out into follow-ups. The install surface is just a thin adapter over that API.

Two ways to install

MCP server. Run npx -y github:MohGanji/mindmapio-mcp and point any MCP client (Claude Desktop, Cursor, and the like) at it. One tool per API primitive.
Agent skill. Skip the MCP client and call the HTTP API directly. Install it with npx skills add MohGanji/mindmapio-mcp.

Both routes use the same primitives and the same token. Pick whichever fits how your agent is wired.

Get a token

Every call authenticates with a personal access token (PAT).

Open mindmap.io, go to settings, then API access.
Generate a token and copy it. You see it once.
Paste it into your MCP client config, or export it as MINDMAP_API_TOKEN.

The token acts as its user. Regenerating it immediately revokes the old one.

Install path 1: the MCP server

Add this block to your MCP client config. npx fetches and builds the server from the public repo, so there is nothing to install ahead of time.

{
  "mcpServers": {
    "mindmapio": {
      "command": "npx",
      "args": ["-y", "github:MohGanji/mindmapio-mcp"],
      "env": {
        "MINDMAP_API_TOKEN": "<your personal access token>"
      }
    }
  }
}

With the Claude Code CLI, the same thing in one line:

claude mcp add mindmapio --env MINDMAP_API_TOKEN=<your token> -- npx -y github:MohGanji/mindmapio-mcp

Restart the client, and the mindmap.io tools show up in your agent. The first run builds from source and takes a few extra seconds; later runs are cached.

By default the server talks to https://mindmap.io. To point it elsewhere, add MINDMAP_API_BASE_URL to the same env block.

Install path 2: the agent skill

If your agent supports skills, install it with one command:

npx skills add MohGanji/mindmapio-mcp

This works with Claude Code and other agents listed on skills.sh. It teaches your agent the same primitives as plain curl calls, including the recursion pattern for auto-expand. You can also read it at skills/mindmapio/SKILL.md.

Set your token first:

export MINDMAP_API_TOKEN="<your personal access token>"
export MINDMAP_API_BASE_URL="https://mindmap.io"   # optional, this is the default

Hello world: build a map and read it back

Create a map, add a prompt node, run it, and read the answer. With the MCP server, call the tools in this order.

// 1. Create a map with a root node.
create_map   { "title": "Hello", "data": { "rootId": "root",
               "nodes": { "root": { "id": "root", "text": "Hello", "children": [] } } } }
//   -> { "id": "MAP_ID" }

// 2. Create a prompt node under the root. Content is the messages array.
create_node  { "mapId": "MAP_ID", "nodeId": "q1", "parentId": "root", "nodeType": "prompt",
               "messages": [{ "role": "user", "parts": [{ "type": "text", "text": "Say hi in one word." }] }] }

// 3. Run the node. The call blocks until the answer is ready.
submit_node  { "mapId": "MAP_ID", "nodeId": "q1" }
//   -> { "nodeId": "q1", "status": "complete", "messages": [ ... ] }

// 4. Read it back.
get_node     { "mapId": "MAP_ID", "nodeId": "q1" }

The skill route runs the same four steps as curl calls. Here is the create-run-read core.

mm() { curl -sS -H "Authorization: Bearer $MINDMAP_API_TOKEN" \
  -H "Content-Type: application/json" "$MINDMAP_API_BASE_URL$@"; }

# create a map with a root
MAP=$(mm /api/mindmaps -X POST -d '{"title":"Hello","data":{"rootId":"root","nodes":{"root":{"id":"root","text":"Hello","children":[]}}}}' | jq -r '.id')
# add a prompt node under the root (content is the messages array)
mm /api/mindmaps/$MAP/nodes -X POST -d '{"nodeId":"q1","parentId":"root","data":{"node_type":"prompt","messages":[{"role":"user","parts":[{"type":"text","text":"Say hi in one word."}]}]}}'
# run it and read the answer back
mm /api/mindmaps/$MAP/nodes/q1/submit -X POST -d '{}'

Node ids are minted client-side, so your agent can reference an id it chose while building a subtree before that node persists.

What your agent can do

One tool per API primitive, grouped by what they do.

Tool	What it does
`list_maps`	List your maps, metadata only, newest first.
`get_map`	Read a full map including its node tree.
`get_node`	Read one node; its `children` lists child ids.
`get_subtree`	Read a nested tree; set `depth` or omit it for the whole subtree.
`create_map`	Create a map with an initial root node.
`delete_map`	Delete a map; cascades to its nodes.
`create_node`	Add a node; `nodeId` optional, a uuid is minted when omitted.
`update_node`	Edit a node’s content (messages) or settings; no model call, not metered.
`delete_node`	Delete a node and its descendants; the root cannot be deleted.
`submit_node`	Run a node through a model; blocks on ancestors; metered.
`auto_expand`	Queue 1 to 4 follow-up children; submit each yourself.
`retry_node`	Re-run a failed node; `force` to re-expand.
`interrupt_node`	Stop an in-flight node; idempotent; not metered.

Auto-expand queues one level of follow-up prompts and does not run them, so your agent owns the recursion. Call auto_expand, submit each returned child, and repeat to go deeper at whatever breadth and depth you choose. Submit blocks until ancestors finish, so each child sees complete parent context.

Security

Never commit your token. Keep it in your MCP client config or an environment variable, not in source control.
The token is sent only as the Authorization bearer header and is never logged. Config and API errors carry no secret.
Treat the PAT like a password. If it leaks, regenerate it in settings, which revokes the old one immediately.

Reference

OpenAPI spec: GET /api/openapi.json, the authoritative contract for every request and response shape.
Source, MCP server, and skill: github.com/MohGanji/mindmapio-mcp.

Generate a token, paste the install block, and have your agent build its first map.