Xmind Mcp

🧠 XMind MCP Server

[](https://github.com/sc0tfree/xmind-mcp/actions/workflows/tests.yml) [](https://www.python.org/downloads/) [](https://opensource.org/licenses/MIT)

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sc0tfree
• Source: sc0tfree/xmind-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.