mindmapio-mcp

Tip: Give this README to your agent and ask it to install the MCP.

Give your AI agent a place to build and keep what it learns. Connect it to mindmap.io and it turns research, plans, and conversations into a real map you can open, grow, and share. Your agent reads existing maps, adds and edits nodes, runs prompts on them, and fans any topic out into follow-up questions, all through your own mindmap.io account.

Three ways to set it up:

Claude plugin. One install command and one masked prompt for your token.
MCP server. One line in your MCP client config (Claude Desktop, Cursor, and other MCP clients).
Agent skill. Install it with npx skills so your agent works with mindmap.io directly, no MCP client needed.

Get a token

Every call uses a personal access token from your account.

Open mindmap.io, go to settings, then API access.
Generate a token and copy it. You only see it once.
Save it as MINDMAP_API_TOKEN, or paste it into the plugin's token prompt.

The token acts as you. Regenerate it any time and the old one stops working instantly.

Option 1: Claude plugin

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

Claude Code prompts for your API token, masks it, and stores it in your OS keychain. Restart, and the tools are live. SETUP.md walks Claude through the same steps, and through what to check when something does not connect.

The plugin ships the MCP server, a skill on how to shape a map well, and the direct-HTTP skill below. No slash commands and no sub-agents.

Option 2: MCP server

Add this to your MCP client config. npx fetches and runs the package for you:

{
  "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

The first run builds from source, so it takes a few extra seconds. Later runs are cached.

Settings

Env var	Required	Default	What it does
`MINDMAP_API_TOKEN`	yes	—	Your personal access token. Sent as `Authorization: Bearer <token>`. Never logged.
`MINDMAP_API_BASE_URL`	no	`https://mindmap.io`	API base URL.

What your agent can do

Nineteen tools, one per operation in the Mindmap.io node API.

Tool	What it does
`list_maps`	List your maps, newest first.
`get_map`	Read a whole map and its node tree.
`get_node`	Read one node.
`get_subtree`	Read a node and its children, as deep as you want.
`create_map`	Start a new map.
`delete_map`	Delete a map and everything in it.
`publish_map`	Publish a map and get its shareable + embed links.
`unpublish_map`	Make a published map private again.
`set_map_layout`	Arrange a map as a tree, top-down, or with branches on both sides.
`send_feedback`	Pass the user's bug report or idea to the mindmap.io team.
`create_node`	Add a node under a parent.
`update_node`	Edit a node's content, note, type, or model.
`delete_node`	Remove a node and its children.
`submit_node`	Run a node through the model and get the answer back.
`auto_expand`	Turn a node into follow-up questions for your agent to run.
`retry_node`	Re-run a node that failed.
`interrupt_node`	Stop a node that is still running.
`upload_attachment`	Upload an image or PDF from this machine to attach to a node.
`read_attachment`	Save an uploaded file back to this machine.

create_node mints a node id for you when you leave it out, so your agent can lay out a whole branch in one pass.

Each tool's description and its title / readOnlyHint / destructiveHint annotations are generated from the OpenAPI document rather than written here, so what your agent reads is the contract the API enforces. See Regenerating the tool list.

Option 3: agent skills

Install the skills with one command:

npx skills add MohGanji/mindmapio-mcp

This works with Claude Code and other agents that support skills (browse them at skills.sh). Two skills ship here:

skills/mindmapio/SKILL.md teaches the same actions over plain HTTP, no MCP client required.
skills/map-shaping/SKILL.md teaches how to shape a map: what belongs in the root node, when to branch versus append, and when to fan out.

Set your token first:

export MINDMAP_API_TOKEN="<your personal access token>"

Hello world

Create a map, add a question, run it, and read the answer. Node content is sent as messages, a UIMessage array ({ role, parts: [{ type: "text", text }] }). With the MCP server, call the tools in order:

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

// 2. Add a question under the root.
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 it. The call waits 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 API also still accepts a legacy text field for node content, but messages is the canonical shape.

The skill at skills/mindmapio/SKILL.md shows the same flow as curl commands.

Keep your token safe

Never commit your token. Keep it in the plugin's token prompt, your MCP client config, or an environment variable.
It is sent only as the Authorization header and is never logged. Config and error messages carry no secret.
Treat it like a password. If it leaks, regenerate it in settings and the old one stops working right away.

Layout

.claude-plugin/   plugin.json and the self-hosted marketplace manifest
.mcp.json         the plugin's connector: the stdio server below, token from userConfig
skills/           the agent skills, also what `npx skills add` installs
server/           the stdio MCP server (src, tests, and the vendored OpenAPI document)
SETUP.md          first-install instructions for Claude

The root package.json is the server's, so npx -y github:MohGanji/mindmapio-mcp still resolves: it builds server/dist and runs it.

Develop

npm install
npm test        # vitest against a mocked HTTP layer, no live backend needed
npm run build   # tsc -> server/dist/

Regenerating the tool list

Tool descriptions and annotations come from server/spec/openapi.json, a vendored mirror of the published https://mindmap.io/api/openapi.json. Refresh it with:

npm run sync:openapi

Drift is checkable in one line:

npm run sync:openapi && git diff --exit-code server/spec

It fetches the published document on purpose, never a local checkout of the API repo, which can hold unpushed edits that would ship a tool list nobody can reach. It refuses to write a document whose operations are missing their x-mcp annotations (title, readOnlyHint, destructiveHint), because a tool without them is a rejection criterion for Anthropic's directories, and leaves the vendored copy untouched in that case.

The skill is held to the same document

buildTools joins the tool list to that document in both directions, and server/test/skill-parity.test.ts joins skills/mindmapio/SKILL.md to it the same way: every documented operation has to be named, called in a worked example, and taught with the query or header inputs and the operation-specific failures (a 409, a 413, a 429) the document declares for it — and a section teaching an endpoint the document does not describe fails too. That is the third leg of ADR 0029's parity invariant, unenforced until the skill had quietly drifted to 15 of 17 operations.

Editing that skill is half a change: mindmap.io serves a mirror of it with a SHA-256 digest, so marketing/scripts/sync-agent-skills.mjs has to be re-run there once the edit is pushed here.

License

MIT

mindmap

Documentation