XMind Server

Tests Python License

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:

1. Load the .xmind file (a ZIP containing content.json)
2. Find the target topic/sheet by its stable UUID
3. Mutate the in-memory structure
4. Validate against a JSON schema
5. 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