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

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

Related MCP server: MCP Jupyter Server

🛠️ Tools

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

Map Management

Topic CRUD

Search & Query

Sheet Management

Relationships

Annotations

⚙️ 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