@lifeng688/xmind-mcp

An MCP server for creating, reading, searching, editing, and exporting XMind mind map files — no desktop automation, just clean file I/O.

Features

| Tool | Description | |---|---| | create_mindmap | Create a .xmind file from a JSON topic tree | | read_mindmap | Parse .xmind → structured JSON | | markdown_to_mindmap | Convert Markdown → .xmind | | export_to_markdown | Export .xmind → Markdown | | list_mindmaps | List all .xmind files in workspace | | add_topic | Add a child topic under an existing node | | update_topic | Update title, note, labels, or markers | | delete_topic | Delete a topic and its children | | search_topics | Search by title, note, or labels |

Installation

npm install
npm run build

Usage

npm run dev    # development mode (hot-reload)
npm start      # run compiled server
npm run inspect # launch MCP Inspector

Configuration

| Variable | Default | Description | |---|---|---| | XMIND_WORKSPACE_DIR | ./data/mindmaps | Root directory for .xmind files | | XMIND_AUTO_BACKUP | true | Auto-backup before modifications | | XMIND_AUDIT_LOG | true | Write audit log to logs/audit.log | | XMIND_MAX_TOPICS | 500 | Max topics per mind map |

Claude Desktop / Cursor

{
  "mcpServers": {
    "xmind-mcp": {
      "command": "npx",
      "args": ["-y", "@lifeng688/xmind-mcp"]
    }
  }
}

Or with a local install:

{
  "mcpServers": {
    "xmind-mcp": {
      "command": "node",
      "args": ["path/to/xmind-mcp/dist/index.js"]
    }
  }
}

Tool Examples

Create a mindmap

{
  "name": "create_mindmap",
  "arguments": {
    "title": "Project Plan",
    "root": {
      "title": "Project Plan",
      "children": [
        { "title": "Phase 1", "children": [{ "title": "Requirement" }, { "title": "Design" }] },
        { "title": "Phase 2" }
      ]
    },
    "outputPath": "project-plan.xmind"
  }
}

Read a mindmap

{ "name": "read_mindmap", "arguments": { "filePath": "project-plan.xmind" } }

Search topics

{ "name": "search_topics", "arguments": { "filePath": "project-plan.xmind", "query": "urgent" } }

Add / Update / Delete topic

// add_topic
{ "name": "add_topic", "arguments": { "filePath": "project-plan.xmind", "parentTopicId": "topic-xyz", "title": "New Branch" } }

// update_topic
{ "name": "update_topic", "arguments": { "filePath": "project-plan.xmind", "topicId": "topic-xyz", "title": "Renamed", "labels": ["urgent"] } }

// delete_topic
{ "name": "delete_topic", "arguments": { "filePath": "project-plan.xmind", "topicId": "topic-to-remove" } }

Markdown ↔ Mindmap

{
  "name": "markdown_to_mindmap",
  "arguments": {
    "markdown": "# My Map\n\n## Branch A\n* Sub-item 1\n* Sub-item 2",
    "outputPath": "from-markdown.xmind"
  }
}

{ "name": "export_to_markdown", "arguments": { "filePath": "project-plan.xmind" } }

Security

• Path Guard: All paths resolved through resolveWorkspacePath() — prevents directory traversal (../) attacks.
• Auto Backup: Original file backed up to workspaceDir/.backup/ before mutations.
• Audit Log: Every tool call logged as JSON line to logs/audit.log.

Limitations

1. Modern XMind format only (ZIP + content.json). Legacy XMind 8 (content.xml) returns a clear error.
2. No support for styles, layouts, images, attachments, or relationship lines.
3. Edit operations rewrite the entire file — not a zip-level patch.
4. Multi-sheet files: only the first sheet is operated on.

Architecture

src/
├── index.ts              # Entry point
├── server.ts             # MCP server setup
├── config/config.ts      # Environment-based config
├── utils/                # Errors, result builders
├── xmind/                # Reader, writer, converter, markdown parser/exporter
├── security/             # Path guard, backup, audit log
└── tools/                # One file per MCP tool

License

MIT

Roadmap

See docs/roadmap.md.