# 🧠 XMind MCP Server

[![Tests](https://img.shields.io/github/actions/workflow/status/sc0tfree/xmind-mcp/tests.yml?style=for-the-badge&label=tests)](https://github.com/sc0tfree/xmind-mcp/actions/workflows/tests.yml)
[![Python](https://img.shields.io/badge/python-3.12%2B-3776ab?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green?style=for-the-badge)](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](https://gofastmcp.com/) (Python) and managed with [Poetry](https://python-poetry.org/).

> [!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](https://python-poetry.org/docs/#installation)

### Install

```bash
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):

```json
{
  "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

```bash
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:

```bash
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
```