Mindmapio

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.

Two ways to set it up:

1. MCP server. One line in your MCP client config (Claude Desktop, Cursor, and other MCP clients).
2. 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.

1. Open mindmap.io, go to settings, then API access.
2. Generate a token and copy it. You only see it once.
3. Save it as MINDMAP_API_TOKEN, or paste it into your MCP client config.

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

Option 1: 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

What your agent can do

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.

Option 2: agent skill

Install the skill 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). It teaches your agent the same actions over plain HTTP, including how to expand a node into follow-up questions and run each one. You can also read it directly at skills/mindmapio/SKILL.md.

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

Develop

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

License

MIT