# Xmind Mcp

> MCP server for incremental editing of XMind mind maps - 19 atomic tools for LLMs to read, create, and surgically modify .xmind files

- **Type:** MCP server
- **Install:** `agentstack add mcp-sc0tfree-xmind-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sc0tfree](https://agentstack.voostack.com/s/sc0tfree)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sc0tfree](https://github.com/sc0tfree)
- **Source:** https://github.com/sc0tfree/xmind-mcp

## Install

```sh
agentstack add mcp-sc0tfree-xmind-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🧠 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](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
```

## 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](https://github.com/sc0tfree)
- **Source:** [sc0tfree/xmind-mcp](https://github.com/sc0tfree/xmind-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sc0tfree-xmind-mcp
- Seller: https://agentstack.voostack.com/s/sc0tfree
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.