Let your AI agents build mindmaps with mindmap.io MCP

Install the mindmap.io MCP server or skill, and your agent can build, run and read maps in your account.

After this guide, your AI agent can build maps in your mindmap.io account. It creates a map, adds a root topic and questions under it, runs each question through a model, and reads the answers back. The map stays in your account, where you can open it in the browser, keep growing it, and share it.

This page covers the token route, for any MCP client that cannot sign in through a browser. Claude, ChatGPT, Claude Code, Codex and VS Code can all sign in to mindmap.io instead, with no token. Each has its own guide in the links at the end.

How it works

Every mindmap.io node can hold an AI conversation, and the node API gives an agent the same actions a person has in the app: create a map, add nodes, run a node through a model, and expand a node into follow-up questions. The MCP server and the skill both call that API with your token.

There are three ways to install it:

  1. Claude Code plugin. Two commands, and Claude Code asks for your token and stores it in your OS keychain.
  2. MCP server. One block in your MCP client’s config, for Claude Desktop, Cursor and other MCP clients.
  3. Agent skill. One command, and your agent calls the HTTP API directly, with no MCP client.

Get a token

Every call uses a personal access token.

  1. Open mindmap.io, go to settings, then API access.
  2. Generate a token and copy it. You see it only once.
  3. Paste it into your MCP client config or the plugin’s prompt, or export it as MINDMAP_API_TOKEN.

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

Option 1: the Claude Code plugin

In Claude Code, run:

/plugin marketplace add MohGanji/mindmapio-mcp
/plugin install mindmapio@mindmap-io

Claude Code asks for your token, masks it, and stores it in your OS keychain. Restart Claude Code and the mindmap.io tools are available. The plugin includes the MCP server and the skills described below.

Option 2: the MCP server

Add this block to your MCP client config. npx fetches and builds the server from the public repo, so you don’t install anything first.

{
  "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 setup is 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 appear in your agent. The first run builds from source and takes a few extra seconds. Later runs are cached.

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

Option 3: the agent skill

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

npx skills add MohGanji/mindmapio-mcp

This works with Claude Code and the other agents listed on skills.sh.

It installs two skills. One teaches the API as plain curl calls, including how to repeat auto-expand to go deeper. The other teaches how to shape a map: what goes in the root, when to branch, and when to fan out. You can read the first 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

Build a map and read it back

This example creates a map, adds a prompt node, runs it, and reads 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", "nodeType": "data",
               "messages": [{ "role": "user", "parts": [{ "type": "text", "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" }

With the skill, the same steps are curl calls:

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","nodeType":"data","messages":[{"role":"user","parts":[{"type":"text","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 '{}'

Your agent chooses the node ids, so it can lay out a whole branch and refer to nodes before they are saved.

What your agent can do

The MCP server has one tool per operation in the API.

ToolWhat it does
list_mapsList your maps, metadata only, newest first.
get_mapRead a full map, including its node tree and layout.
get_nodeRead one node; its children lists child ids.
get_subtreeRead a nested tree; set depth, or omit it for the whole subtree.
create_mapCreate a map with an initial root node.
delete_mapDelete a map and all its nodes.
publish_mapPublish a map and get its public link and embed link.
unpublish_mapMake a published map private again; its links stop working.
set_map_layoutArrange the map as a tree, top-down, or with branches on both sides.
rename_mapGive the map a name that stays when its root node changes.
create_nodeAdd a node; nodeId is optional, and a uuid is minted when you omit it.
update_nodeEdit a node’s content, note, type, model or color; no model call, not metered.
delete_nodeDelete a node and its descendants; the root cannot be deleted.
submit_nodeRun a node through a model; waits for its ancestors; metered.
auto_expandQueue one level of follow-up questions under a node; submit each yourself.
retry_nodeRe-run a failed node; force re-expands an expand node.
interrupt_nodeStop a node that is still running; not metered.
upload_attachmentUpload an image or PDF to a map, to attach to a node.
read_attachmentRead back an uploaded file.

auto_expand creates one level of follow-up questions and does not run them, so your agent decides how deep to go. Call auto_expand, submit each child it returns, and repeat. The model decides how many follow-ups each level gets, based on the node’s own thread. Because submit_node waits for ancestors to finish, each child runs with its full branch as context.

Images and PDFs can be up to 10 MB each, with up to 5 per node. Runs through submit_node use the same credits as running a prompt in the app.

Keep your token safe

  • Don’t commit your token. Keep it in your MCP client config, the plugin’s prompt, or an environment variable.
  • The token is sent only in the Authorization header and is never logged. Error messages don’t include it.
  • Treat it like a password. If it leaks, regenerate it in settings, which revokes the old one immediately.

Reference

Generate a token in mindmap.io, install the server or skill, and ask your agent to build its first map.