@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

# 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):

{
  "mcpServers": {
    "xmind": {
      "command": "npx",
      "args": ["@lifeng688/xmind-mcp"],
      "env": {
        "XMIND_WORKSPACE_DIR": "E:/xmind-workspace"
      }
    }
  }
}

Claude Desktop / Cursor (macOS / Linux)

{
  "mcpServers": {
    "xmind": {
      "command": "npx",
      "args": ["@lifeng688/xmind-mcp"],
      "env": {
        "XMIND_WORKSPACE_DIR": "/Users/your-name/xmind-workspace"
      }
    }
  }
}

Claude Code

# 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

{
  "id": "task-1",
  "title": "Implement style adapter",
  "stylePreset": "task",
  "markers": ["todo"]
}

Topic with web link (via href)

{
  "id": "xmind-docs",
  "title": "XMind Docs",
  "href": "https://xmind.app/"
}

Topic with structured link

{
  "id": "resource-npm",
  "title": "npm package",
  "link": {
    "type": "web",
    "target": "https://www.npmjs.com/package/@lifeng688/xmind-mcp"
  }
}

Topic with explicit style

{
  "id": "risk-node",
  "title": "High risk item",
  "style": {
    "textColor": "#991B1B",
    "fillColor": "#FEE2E2",
    "borderColor": "#DC2626",
    "branchColor": "#DC2626",
    "bold": true
  }
}

Topic with marker

{
  "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:

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 for planned features and milestones.