# xmind-mcp

An MCP (Model Context Protocol) server that lets Claude read and write `.xmind` files. Use Claude to generate, edit, and analyze mind maps directly in XMind.

## Features

- Read existing `.xmind` files as a structured JSON tree
- Create new mind maps from scratch
- Add, update, and delete nodes
- Supports basic node styles (background color, text color, branch color)
- Includes a Claude Code skill for guided mind map editing workflow

## Requirements

- Python 3.10+
- [Claude Code](https://claude.ai/code)
- [XMind](https://xmind.app) (to view the generated files)

## Installation

### 1. Install dependencies

```bash
pip install mcp
```

### 2. Register the MCP server

Add to `~/.mcp.json`:

```json
{
  "mcpServers": {
    "xmind-tools": {
      "command": "python3",
      "args": ["/path/to/xmind-mcp/server.py"]
    }
  }
}
```

### 3. (Optional) Install the skill

Copy `skills/xmind-editor/` to your Claude Code skills directory:

```bash
cp -r skills/xmind-editor ~/.claude/skills/
```

## Usage

Restart Claude Code after registration. Then ask Claude:

```text
Help me create a mind map about AWS architecture, save to ~/Desktop/aws.xmind
```

Claude will plan the structure, confirm with you, then write the file. Open or reload the file in XMind to see the result.

### Available Tools

| Tool            | Description                                |
| --------------- | ------------------------------------------ |
| `read_mindmap`  | Read an `.xmind` file as a JSON tree       |
| `write_mindmap` | Write a full JSON tree to an `.xmind` file |
| `add_node`      | Add a child node under a parent            |
| `update_node`   | Update a node's title or style             |
| `delete_node`   | Delete a node and its children             |

## Node Format

```json
{
  "id": "uuid",
  "title": "Node title",
  "style": {
    "bg": "#ffffff",
    "fg": "#000000",
    "branch": "#3498db"
  },
  "children": []
}
```

All style fields are optional. Colors are hex strings (`#RRGGBB`).

### Colors

| Field          | Description           | Example   |
| -------------- | --------------------- | --------- |
| `bg`           | Node background color | `#ff0000` |
| `fg`           | Text color            | `#ffffff` |
| `branch`       | Branch line color     | `#3498db` |
| `border_color` | Border line color     | `#333333` |

### Shape

Values sourced from official xmind-sdk-js and open source XMind implementations.

| Field   | Description | Values                                               |
| ------- | ----------- | ---------------------------------------------------- |
| `shape` | Node shape  | `roundedRect` `rect` `underline` `ellipserect`       |

### Branch and Border

| Field | Description | Values |
| --- | --- | --- |
| `branch_style` | Branch curve style | `curve` `roundedElbow` `elbow` `straight` `arrowedCurve` `bight` `roundedfold` |
| `branch_pattern` | Branch line pattern | `solid` `dash` `handdrawn-dash` `none` |
| `border_color` | Border line color | hex `#RRGGBB` |
| `border_width` | Border line width | `"2pt"` `"0pt"` |
| `border_pattern` | Border line pattern | `solid` `dash` `handdrawn-dash` `none` |

### Text

| Field           | Description   | Example  |
| --------------- | ------------- | -------- |
| `bold`          | Bold          | `true`   |
| `italic`        | Italic        | `true`   |
| `strikethrough` | Strikethrough | `true`   |
| `font_size`     | Font size     | `"14pt"` |

> `shape` and `branch_style` values are prefixed automatically — use the short name only (e.g. `"roundedRect"`, not `"org.xmind.topicShape.roundedRect"`).

### Example with styles

```json
{
  "id": "root",
  "title": "My Project",
  "children": [
    {
      "id": "node-1",
      "title": "Critical",
      "style": {
        "bg": "#ff0000",
        "fg": "#ffffff",
        "branch": "#ff0000",
        "bold": true,
        "shape": "roundedRect"
      },
      "children": []
    },
    {
      "id": "node-2",
      "title": "Reference",
      "style": {
        "branch_pattern": "dash",
        "border_color": "#999999",
        "border_width": "1pt"
      },
      "children": []
    }
  ]
}
```

## Development

```bash
pip install -e ".[dev]"
pytest tests/
```

## License

MIT