xmind-mcp

# @lifeng688/xmind-mcp An MCP (Model Context Protocol) server for creating, reading, searching, incrementally editing, styling, linking, and exporting local XMind mind map files. Let AI assistants like Claude Desktop, Cursor, and Claude Code create and manipulate `.xmind` files directly — no desktop automation, no mouse simulation, just clean file I/O. ## Features ### Core Mind Map Features | Tool | Description | |---|---| | `create_mindmap` | Create a new `.xmind` file from a JSON topic tree | | `read_mindmap` | Read and parse an existing `.xmind` file into structured JSON | | `markdown_to_mindmap` | Convert Markdown (headings + lists) into a `.xmind` file | | `export_to_markdown` | Export a `.xmind` file to Markdown format | | `list_mindmaps` | List all `.xmind` files in the workspace directory | | `add_topic` | Add a child topic under an existing node | | `update_topic` | Update title, note, labels, markers, hyperlink, link, stylePreset, or style of an existing topic | | `delete_topic` | Delete a topic and all its children (root is protected) | | `search_topics` | Search topics by title, note, labels, hyperlink, link target, stylePreset, and markers | ### v0.2.0 — Visual Metadata & Links - **Topic style support** — `fillColor`, `textColor`, `borderColor`, `branchColor`, `fontSize`, `bold`, `italic`, `underline`, `borderWidth`, `branchWidth`, `shape`, `fontFamily` - **Native href support** — Simple web URL shorthand (`href: "https://..."`) - **Backward-compatible hyperlink field** — `hyperlink` works as an alias for `href` - **Structured link support** — `link: { type: "web"|"file"|"folder"|"topic", target: "..." }` - **Marker support** — `priority-1` through `priority-5`, `done`, `todo`, `star`, `heart`, `flag`, `warning`, `risk`, `blocked`, `check`, `progress`, `important`, `smiley-*`, `arrow-*`, `callout` - **stylePreset support** — `important`, `success`, `warning`, `danger`, `info`, `idea`, `task`, `done`, `blocked` (each resolves to colors + optional markers) - **Markdown link parsing** — `[title](url)` headings and list items become topics with web links - **Markdown export preserves links** — web links are exported as Markdown links `[title](url)` - **Notes and labels support** — Plain text notes and free-form labels/tags - **Improved tool descriptions** — All MCP tool descriptions now guide LLMs to use visual enhancements for richer mind maps ## Installation ```bash # Global install npm install -g @lifeng688/xmind-mcp # Or run directly without installing npx @lifeng688/xmind-mcp ``` ## MCP Client Configuration ### Claude Desktop / Cursor (Windows) Add to your MCP configuration file (`mcp.json`): ```json { "mcpServers": { "xmind": { "command": "npx", "args": ["@lifeng688/xmind-mcp"], "env": { "XMIND_WORKSPACE_DIR": "E:/xmind-workspace" } } } } ``` ### Claude Desktop / Cursor (macOS / Linux) ```json { "mcpServers": { "xmind": { "command": "npx", "args": ["@lifeng688/xmind-mcp"], "env": { "XMIND_WORKSPACE_DIR": "/Users/your-name/xmind-workspace" } } } } ``` ### Claude Code ```bash # Add to your project's .claude/settings.local.json # Or run directly: npx @lifeng688/xmind-mcp ``` ## Environment Variables | Variable | Default | Description | |---|---|---| | `XMIND_WORKSPACE_DIR` | `./data/mindmaps` | Root directory for all `.xmind` files. **Strongly recommended** to set this to avoid unrestricted file access. | | `XMIND_OUTPUT_DIR` | (none) | Optional additional output directory. | | `XMIND_ALLOW_OVERWRITE` | `false` | Whether to allow overwriting existing `.xmind` files. | | `XMIND_AUTO_BACKUP` | `true` | Automatically back up files before modification. | | `XMIND_AUDIT_LOG` | `true` | Write audit log to `logs/audit.log`. | | `XMIND_MAX_TOPICS` | `500` | Maximum topics per mind map. | | `LOG_LEVEL` | `info` | Logging level (`debug`, `info`, `warn`, `error`). | | `NODE_ENV` | `production` | Runtime environment. | > **Recommendation:** Always set `XMIND_WORKSPACE_DIR` to a dedicated directory. Do not point it to system root or sensitive directories. ## Tools | Tool | Description | |---|---| | `create_mindmap` | Create a new `.xmind` file from a JSON topic tree. Supports `stylePreset`, `link`, `href`, `style`, `markers`, `labels`, `note`. | | `read_mindmap` | Read and parse an existing `.xmind` file. Returns `title`, `root` tree (with all v0.2 fields), and `topicCount`. | | `markdown_to_mindmap` | Convert Markdown to `.xmind`. Parses `[title](url)` headings and list items into topics with web links. | | `export_to_markdown` | Export `.xmind` to Markdown. Web links become `[title](url)`, stylePreset becomes `Style: name`, other links become `Link: type:url`. | | `list_mindmaps` | List all `.xmind` files in the workspace directory (recursive). | | `add_topic` | Add a child topic under an existing node. Supports `link`, `href`, `stylePreset`, `style`, `markers`, `labels`, `note`. | | `update_topic` | Update any property of an existing topic. Supports `title`, `note`, `labels`, `markers`, `href`, `link`, `stylePreset`, `style`. Pass `null` to remove a field. | | `delete_topic` | Delete a topic and its entire subtree. Root is protected. | | `search_topics` | Search topics by title, note, labels, href, link target, stylePreset, and markers. | ## Topic Schema Examples ### Basic topic ```json { "id": "task-1", "title": "Implement style adapter", "stylePreset": "task", "markers": ["todo"] } ``` ### Topic with web link (via href) ```json { "id": "xmind-docs", "title": "XMind Docs", "href": "https://xmind.app/" } ``` ### Topic with structured link ```json { "id": "resource-npm", "title": "npm package", "link": { "type": "web", "target": "https://www.npmjs.com/package/@lifeng688/xmind-mcp" } } ``` ### Topic with explicit style ```json { "id": "risk-node", "title": "High risk item", "style": { "textColor": "#991B1B", "fillColor": "#FEE2E2", "borderColor": "#DC2626", "branchColor": "#DC2626", "bold": true } } ``` ### Topic with marker ```json { "id": "milestone", "title": "Release v0.2.0", "markers": ["done", "star"], "stylePreset": "success" } ``` ## Natural Language Examples You can talk to your AI assistant naturally. Here are some examples: 1. **Project planning** > Create a project roadmap mind map for xmind-mcp v0.2.0. Use task, done, warning, blocked, and important styles. Add npm and GitHub links to the release resources. 2. **Markdown conversion** > Convert this Markdown outline into an XMind mind map. Preserve Markdown links as real topic links. 3. **Adding resources** > Add a new resource topic under "Resources" with a web link to https://xmind.app/ and style it as important. 4. **Risk analysis** > Create a risk analysis mind map. Use warning for normal risks, danger for severe risks, success for mitigations, and info for background notes. ## What's New in v0.2.0 - **Visual metadata support** — Topics can now have colors, bold text, font sizes, and borders via the `style` field. - **stylePreset support** — Nine semantic presets (`important`, `success`, `warning`, `danger`, `info`, `idea`, `task`, `done`, `blocked`) that resolve to consistent color schemes and optional markers. - **Structured topic links** — `link: { type, target }` for web, file, folder, and topic references. - **Native href support** — Simple `href: "https://..."` for web URLs, preferred over the legacy `hyperlink` field. - **Marker expansion** — Support for semantic markers beyond XMind native ones (`important`, `flag`, `check`, `progress`, `blocked`, `warning`, `risk`), persisted via custom metadata for round-trip fidelity. - **Markdown link parsing** — `### [Title](url)` headings and `- [Title](url)` list items are parsed into topics with web links. - **Markdown export preserves links** — Web links are exported as `[title](url)`, other link types as `Link: type:url`. - **Improved tool descriptions** — All MCP tool descriptions now guide LLMs to use visual enhancements for richer mind maps. ## Testing This project uses an MCP JSON test runner to validate core capabilities: ```bash node run-mcp-json-test.mjs ./tests/xmind/v0.2/01-style-color.json node run-mcp-json-test.mjs ./tests/xmind/v0.2/02-hyperlink.json node run-mcp-json-test.mjs ./tests/xmind/v0.2/03-markers-priority.json node run-mcp-json-test.mjs ./tests/xmind/v0.2/04-topic-link-support.json node run-mcp-json-test.mjs ./tests/xmind/v0.2/05-style-preset.json node run-mcp-json-test.mjs ./tests/xmind/v0.2/06-markdown-link-parsing.json node run-mcp-json-test.mjs ./tests/xmind/v0.2/06-markdown-link-parsing.json ``` Test coverage: - `01-style-color.json` — stylePreset and raw style round-trip - `02-hyperlink.json` — href/hyperlink read/write across all nesting levels - `03-markers-priority.json` — semantic markers with full round-trip fidelity - `04-topic-link-support.json` — web/file/folder/topic link support - `05-style-preset.json` — stylePreset resolution, markers, update/overwrite - `06-markdown-link-parsing.json` — Markdown link parsing and export ## Security - **Path Guard** — All file paths are resolved through `resolveWorkspacePath()` which prevents directory traversal (`../`) attacks. Files must reside inside the configured workspace directory. - **Auto Backup** — Before any mutating operation (add/update/delete), the original file is backed up to `workspaceDir/.backup/` with a timestamp. - **Audit Log** — Every tool call (success or failure) is logged as a JSON line to `logs/audit.log`. - **Topic Cap** — Configurable maximum number of topics per file (default: 500). - **Workspace restriction** — Always set `XMIND_WORKSPACE_DIR` to a dedicated directory. Do not point it to system root or sensitive directories. - **Local links are user-controlled** — `file:` and `folder:` link types reference local paths. Use them carefully and only with trusted inputs. ## Limitations 1. **Modern format only** — Supports ZIP-based `.xmind` files with `content.json`. Legacy XMind 8 files (`content.xml`) return a clear error. 2. **Single sheet** — Operates on the first sheet of a `.xmind` file. 3. **Full file rewrite** — Edit operations read the full tree, modify in memory, and regenerate the entire `.xmind` file. 4. **No XMind themes or layouts** — Focuses on topic tree structure, not visual layout. 5. **No images or attachments** — These are not supported. ## License MIT ## Roadmap See [docs/roadmap.md](docs/roadmap.md) for planned features and milestones.