🧠 XMind MCP Server

An MCP server for incremental editing of XMind mind maps. Existing XMind MCP tools require the LLM to output an entire mind map as one monolithic JSON blob -- that's token-expensive, error-prone, and makes it impossible to edit existing files. xmind-mcp takes a different approach: 19 atomic tools that let an LLM read, create, and surgically edit .xmind files one operation at a time using stable topic IDs.

Built with FastMCP (Python) and managed with Poetry.

[!NOTE] Unfortunately, XMind does not support live-reloading files from disk. If you have the file open in XMind while making changes via MCP tools, you'll need to close and reopen it to see the updates.

🚀 Quick Start

Prerequisites

Python 3.12+
Poetry

Install

git clone https://github.com/sc0tfree/xmind-mcp.git
cd xmind-mcp
poetry install

Configure Your MCP Client

Add the following to your MCP configuration (e.g. .cursor/mcp.json for Cursor, or ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "xmind": {
      "command": "poetry",
      "args": ["-C", "/path/to/xmind-mcp", "run", "xmind-mcp"]
    }
  }
}

Restart the application after editing.

🛠️ Tools

All tool names are prefixed with xmind_ to avoid collisions with other MCP servers.

Map Management

| Tool | What it does | |------|-------------| | xmind_create_map | Create a new .xmind file with a central topic | | xmind_open_map | Read the full tree structure with all IDs (supports max_depth for large maps) | | xmind_list_maps | Recursively list .xmind files in a directory |

Topic CRUD

| Tool | What it does | |------|-------------| | xmind_add_topic | Add a single child topic to a parent | | xmind_add_subtree | Add a whole branch with nested children in one call | | xmind_update_topic | Update title, notes, labels, markers, href, task status, or structure class | | xmind_delete_topic | Remove a topic and all its descendants | | xmind_move_topic | Move a topic to a different parent or reorder among siblings |

Search & Query

| Tool | What it does | |------|-------------| | xmind_get_topic | Get full JSON details of a topic and its subtree by ID | | xmind_search_topics | Full-text search across titles, notes, and labels |

Sheet Management

| Tool | What it does | |------|-------------| | xmind_add_sheet | Add a new sheet to the file | | xmind_rename_sheet | Rename a sheet | | xmind_delete_sheet | Delete a sheet (cannot delete the last one) |

Relationships

| Tool | What it does | |------|-------------| | xmind_add_relationship | Create a connection line between two topics | | xmind_delete_relationship | Remove a relationship |

Annotations

| Tool | What it does | |------|-------------| | xmind_add_boundary | Add a visual boundary grouping child topics | | xmind_delete_boundary | Remove a boundary | | xmind_add_summary | Add a summary topic spanning a range of children | | xmind_delete_summary | Remove a summary |

⚙️ How It Works

Every tool follows the same pattern:

Load the .xmind file (a ZIP containing content.json)
Find the target topic/sheet by its stable UUID
Mutate the in-memory structure
Validate against a JSON schema
Save back to the ZIP

Files are small (KB range), so this round-trip is instant. The LLM workflow is:

xmind_open_map  →  see the tree with IDs  →  xmind_add_topic / xmind_update_topic / etc.

💡 Practical Example

User: Create a mind map about our product launch

LLM:  xmind_create_map("~/Desktop/launch.xmind", "Product Launch")
      xmind_add_topic(path, root_id, "Marketing")
      xmind_add_topic(path, root_id, "Engineering")
      xmind_add_topic(path, root_id, "Sales")
      xmind_add_subtree(path, marketing_id, [
          {"title": "Social Media", "children": [{"title": "Twitter"}, {"title": "LinkedIn"}]},
          {"title": "Blog Posts"},
      ])

User: Add a note to Engineering about the timeline

LLM:  xmind_update_topic(path, engineering_id, notes="Target launch: Q2 2026")

User: Actually, move Sales under Marketing

LLM:  xmind_move_topic(path, sales_id, marketing_id)

Each call is a single, focused operation. No need to regenerate the entire tree.

🧪 Development

Run Tests

poetry run pytest -v

70+ automated tests cover every tool with round-trip validation (create/modify -> reload from disk -> assert correctness -> schema validation).

Interactive Tests

A visual test harness that builds a real .xmind file through 6 stages, pausing at each checkpoint so you can open it in XMind and verify:

poetry run interactive-tests

Project Structure

xmind_mcp/
  server.py             # FastMCP server with all 19 tools
  xmind_file.py         # XMindFile class: ZIP I/O, tree traversal, lookups
  validator.py          # JSON schema for content.json validation
  utils.py              # UUID generation

tests/
  test_tools.py         # Round-trip tests for every tool
  test_xmind_file.py    # XMindFile unit tests
  test_validator.py     # Schema validation tests
  manual_checkpoint.py  # Interactive 6-stage visual test
  conftest.py           # Shared fixtures

MCP Servers