XMind MCP Server

A Model Context Protocol (MCP) server for parsing and searching XMind mind map files (.xmind). Enables Claude and other AI applications to efficiently extract, search, and manipulate mind map data with token-aware formatting and intelligent error handling.

Features

• Full Document Parsing: Convert entire XMind documents to structured Markdown or JSON format
• Efficient Search: Search nodes by keyword, label, or status marker with breadcrumb path resolution
• Branch Extraction: Extract specific subtrees with optional depth limiting for token optimization
• Multi-Format Support: Handles both Zen (modern JSON-based) and Legacy (XML-based) XMind formats
• Token-Aware Output: Estimates token consumption and provides optimization suggestions
• Error Guidance: Helpful error messages with actionable recovery steps
• Claude Desktop Integration: Ready to use as a Claude Desktop tool

Table of Contents

• Quick Start
• Installation
  • Global Install (Recommended)
  • From Source
• Usage
  • Running the MCP Server
  • Claude Desktop Configuration
  • Command-Line (CLI) Usage
• Tools Documentation
  • parse_xmind
  • search_xmind_nodes
  • get_xmind_node_branch
• Debugging with MCP Inspector
• Development
• Limitations and Known Issues
• Troubleshooting
• Support
• License
• Changelog

Quick Start

Get from zero to a working result in under a minute.

Option A — Global install (fastest)

npm install -g @zengjing/xmind-mcp
xmind-mcp --help                                 # verify install
xmind-mcp ~/Documents/my-mindmap.xmind          # try CLI on a file

Option B — Local dev install

git clone https://github.com/hhtczengjing/xmind-mcp.git
cd xmind-mcp
npm install
npm run build
npm start                                        # launches MCP server on stdio

Then point Claude Desktop at the built dist/index.js (see Claude Desktop Configuration).

Installation

Requirements

• Node.js 18.0 or higher (matches engines.node in package.json)
• npm or yarn package manager

Global Install (Recommended)

The bin field in package.json exposes the xmind-mcp command globally, so most users can skip building from source:

npm install -g @zengjing/xmind-mcp
xmind-mcp --help

This gives you both:

• the xmind-mcp CLI (see Command-Line Usage)
• a runnable MCP server entry point at <npm-prefix>/lib/node_modules/@zengjing/xmind-mcp/dist/index.js

📌 Use npm root -g (macOS/Linux) or %APPDATA%\npm (Windows) to locate dist/index.js for your Claude Desktop config.

From Source

1. Clone the repository

   git clone https://github.com/hhtczengjing/xmind-mcp.git
   cd xmind-mcp
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

4. Verify installation

   npm run lint
   

Usage

Running the Server

Start the MCP server via stdio transport:

npm start

The server will start and listen for MCP protocol requests on stdin/stdout.

For development with hot reload:

npm run dev

Claude Desktop Configuration

To use with Claude Desktop, add the server to your claude_desktop_config.json:

Location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

Configuration:

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

Replace /path/to/xmind-mcp with the absolute path to your xmind-mcp directory.

After adding the configuration, restart Claude Desktop. The three tools will be available to Claude.

Command-Line (CLI) Usage

The project ships a standalone CLI built on the same parser/formatters that power the MCP tools. It's useful for quick inspection, scripting, and CI pipelines.

Script alias (from source): npm run parse -- <file> [options] Global command (after npm install -g): xmind-mcp <file> [options] Direct binary: node dist/cli.js <file> [options]

Usage

xmind-mcp <file-path> [options]

Arguments:
  <file-path>     Path to the .xmind file (supports ~ for home directory)

Options:
  -f, --format    Output format: 'markdown' (default) or 'json'
  -o, --output    Save output to file
  -s, --search    Filter results by keyword (case-insensitive)
  -v, --verbose   Show sheet titles and parsing details
  -h, --help      Show this help message

Examples

# Print a Markdown outline to stdout
xmind-mcp ~/Documents/project-plan.xmind

# JSON output, saved to a file
xmind-mcp ~/Documents/strategy.xmind --format json -o strategy.json

# Filter content by a keyword
xmind-mcp ~/Documents/notes.xmind --search "deadline"

# Verbose mode (shows file metadata + per-sheet titles)
xmind-mcp ~/Documents/notes.xmind -v

The CLI prints a header block with file metadata (format version, sheet count, total topics, parse timestamp) followed by the formatted content, and exits with status code 0 on success or 1 on error.

Tools Documentation

1. parse_xmind

Description: Parse an entire XMind document and return formatted output (Markdown or JSON).

When to use:

• Analyzing complete mind map structures
• Creating summaries or reports from mind maps
• Understanding full document architecture

Parameters:

Parameter	Type	Required	Default	Description
path	string	Yes	-	Absolute file path to the .xmind file. Supports ~ for home directory expansion.
format	string	No	markdown	Output format: markdown (token-efficient, recommended) or json (structured).

Examples:

Tool Call:
  parse_xmind
  path: "~/Documents/project-plan.xmind"
  format: "markdown"

Response:
  Complete mind map structure in Markdown format with token estimate.
  Includes recommendations for large documents (>20K tokens).

Tool Call:
  parse_xmind
  path: "/Users/alice/xmind/strategy.xmind"
  format: "json"

Response:
  Structure summary + full JSON representation with metadata.

Output:

• Formatted content (Markdown or JSON)
• Metadata: file path, XMind format (Zen/Legacy), sheet count, topic count
• Token estimation and optimization suggestions for large documents
• Character count and recommendations for context efficiency

Token Efficiency:

• Markdown format: ~1 token per 4 characters (most efficient)
• JSON format: ~1 token per 3 characters (more detailed metadata)
• Large documents (>20K tokens): Consider using search or branch extraction

2. search_xmind_nodes

Description: Search for nodes in an XMind file by keyword, label, or status marker with breadcrumb path resolution.

When to use:

• Finding specific topics in large mind maps without loading entire document
• Locating nodes by keyword, label, or marker type
• Narrowing context for focused analysis

Parameters:

Parameter	Type	Required	Default	Description
path	string	Yes	-	Absolute file path to the .xmind file. Supports ~ for home directory.
query	string	Yes	-	Search keyword or phrase to match in node titles, notes, or labels.
searchIn	array	No	['title', 'note', 'label']	Fields to search in: title, note, label. Specify subset to optimize.
caseSensitive	boolean	No	false	Enable case-sensitive matching (default: case-insensitive).

Examples:

Tool Call:
  search_xmind_nodes
  path: "~/Documents/project-plan.xmind"
  query: "deadline"
  searchIn: ["title", "note"]

Response:
  Found 3 matches:
  1. Project Deadline
     Path: Project Plan > Timeline > Project Deadline
     Match: title — "deadline"
     Note: Must complete by end of Q3...
  
  2. Milestone Due Date
     Path: Project Plan > Phases > Phase 2 > Milestone Due Date
     Match: note — "Deadline is Sept 30th"
  ...

Tool Call:
  search_xmind_nodes
  path: "/Users/alice/xmind/architecture.xmind"
  query: "API"
  caseSensitive: true
  searchIn: ["title"]

Response:
  Found 2 matches:
  1. REST API Design
     Path: Architecture > Backend > REST API Design
     Match: title — "REST API Design"
  ...

Output:

• Match count and result details
• Breadcrumb paths (root → ... → node) for context
• Match type and matched text excerpt
• Node notes preview (first 80 characters) if available
• Matched nodes have IDs that can be used with get_xmind_node_branch

3. get_xmind_node_branch

Description: Extract a specific node and its subtree (up to specified depth) from an XMind file.

When to use:

• Focusing on specific branches to avoid token overload
• Extracting relevant subtrees for detailed analysis
• Limiting recursion depth for performance
• Narrowing context after search results

Parameters:

Parameter	Type	Required	Default	Description
path	string	Yes	-	Absolute file path to the .xmind file.
nodeId	string	Yes	-	Target node ID to extract. Get IDs via search_xmind_nodes or parse_xmind output.
depth	number	No	unlimited	Maximum recursion depth for children (0 = node only, 1 = children, 2+ = deeper).

Examples:

Tool Call:
  get_xmind_node_branch
  path: "~/Documents/project-plan.xmind"
  nodeId: "topic-42a"
  depth: 2

Response:
  Extracted 8 nodes (depth: 2/2)
  
  - Target Topic
    - Child 1
      - Grandchild 1
      - Grandchild 2
    - Child 2
    > Supporting notes if available...

Tool Call:
  get_xmind_node_branch
  path: "/Users/alice/xmind/strategy.xmind"
  nodeId: "analysis-backend"

Response:
  Extracted 24 nodes (depth: 4/∞)
  
  - Backend Architecture
    - API Layer
      - REST Endpoints
      - GraphQL
    - Database
      - Schema Design
      - Performance Tuning
    ...

Output:

• Node count and depth information
• Extracted subtree in Markdown outline format
• Metadata: actual depth reached vs requested depth
• Suitable for direct analysis or further processing

Debugging with MCP Inspector

The MCP Inspector is the official debugger for MCP servers. It streams ListTools / CallTool traffic so you can verify your install and inspect each request/response without going through Claude Desktop.

# From the project root, with deps installed
npx @modelcontextprotocol/inspector node dist/index.js

In the Inspector UI:

1. Confirm the three tools (parse_xmind, search_xmind_nodes, get_xmind_node_branch) appear under Tools.
2. Pick a tool, fill in path to a real .xmind file, and hit Run.
3. Use the Notifications / Logs pane to see structured log output (the server uses the utils/logger.ts module with info / warn / error levels).

Enable verbose logging in any environment by setting DEBUG=xmind-mcp.

Development

Project Structure

xmind-mcp/
├── src/
│   ├── index.ts                    # MCP server entry point (stdio transport)
│   ├── cli.ts                      # Standalone CLI for local/scripted use
│   ├── core/
│   │   ├── parser.ts              # Unified parser interface
│   │   ├── zen-parser.ts          # Zen (JSON) format handler
│   │   └── legacy-parser.ts       # Legacy (XML) format handler
│   ├── tools/
│   │   ├── parse-tool.ts          # parse_xmind implementation
│   │   ├── search-tool.ts         # search_xmind_nodes implementation
│   │   └── branch-tool.ts         # get_xmind_node_branch implementation
│   ├── formatters/
│   │   ├── markdown-formatter.ts  # Markdown output formatting
│   │   └── json-formatter.ts      # JSON output formatting
│   ├── model/
│   │   ├── types.ts               # Core TypeScript types (XMindNode, XMindSheet, etc.)
│   │   └── schemas.ts             # Zod schemas for input validation
│   └── utils/
│       ├── errors.ts              # Error types and handling
│       ├── file-utils.ts          # File path resolution and validation
│       └── logger.ts              # Structured logging utilities
├── tests/                          # Jest test suite
├── dist/                           # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── jest.config.js

File Descriptions

Core Modules

• parser.ts: Unified interface for parsing both Zen and Legacy formats. Auto-detects format and delegates to appropriate parser.
• zen-parser.ts: Handles modern XMind Zen format (JSON-based). Extracts content.xml from .zip archive.
• legacy-parser.ts: Handles legacy XMind 8 format (XML-based). Parses workbook.xml structure.

Entry Points

• index.ts: MCP server. Listens on stdio and routes parse_xmind / search_xmind_nodes / get_xmind_node_branch calls.
• cli.ts: Standalone CLI (see Command-Line Usage). Built into dist/cli.js and exposed as the xmind-mcp global command.

Tool Implementations

• parse-tool.ts: Full document parsing with format selection. Includes token estimation and optimization suggestions.
• search-tool.ts: Breadth-first search across all sheets with path tracking. Supports field filtering and case sensitivity.
• branch-tool.ts: Tree extraction with depth limiting. Useful for large documents.

Formatters

• markdown-formatter.ts: Converts AST to token-efficient Markdown outline. Escapes special characters and includes metadata.
• json-formatter.ts: Full-featured JSON output with structure summary. Useful for programmatic processing.

Model & Utilities

• types.ts: Core types: XMindNode, XMindSheet, XMindParsedResult, SearchResult, etc.
• schemas.ts: Zod validation schemas for all tool inputs.
• errors.ts: Custom error classes with error codes for specific failure modes.
• file-utils.ts: Path resolution, validation, and node ID verification.
• logger.ts: Structured logging with levels (debug, info, warn, error).

Testing

Run the full test suite:

npm test

Run tests in watch mode:

npm run test:watch

Tests are organized by layer under tests/:

tests/
├── core/                         # Unit tests for individual parsers
│   ├── legacy-parser.test.ts     # XMind 8 (XML) format
│   └── zen-parser.test.ts        # XMind Zen (JSON) format
└── e2e/
    └── mcp-integration.test.ts   # End-to-end MCP protocol flow

The framework is Jest with ts-jest (TypeScript out of the box). All tests run from a clean repo without any external network access — .xmind fixtures are generated or committed locally.

Building

Compile TypeScript to JavaScript:

npm run build

Type check without building:

npm run lint

Architecture Overview

Unified AST Model: Both Zen and Legacy formats are normalized to a single tree structure (XMindNode), simplifying downstream processing.

Stateless Design: All functions are pure and immutable. No server-side state is maintained between requests.

Token-Aware Output: Tools estimate token consumption and suggest optimizations (search/branch extraction for large documents).

Error Guidance: All errors include actionable messages helping users recover (invalid paths, missing nodes, etc.).

Performance: Lazy evaluation where possible, depth limiting in branch extraction, incremental search results.

Limitations and Known Issues

Current Limitations

1. Hyperlinks: Internal node references (href) are preserved but not resolved to actual node content
2. Relationships/Connectors: Cross-node relationships are parsed but not included in Markdown output (available in JSON format)
3. Rich Text: Multi-formatted text within notes is flattened to plain text
4. Images & Media: Embedded images and media are not extracted or referenced
5. Styling: Font colors, sizes, and other visual formatting are not preserved
6. Comments: XMind 2024 comment annotations are not extracted

Token Limitations

• Large mind maps (>50K nodes) may exceed Claude's context window even with branch extraction
• Recommend using search to narrow scope for very large documents
• JSON format uses more tokens than Markdown format (use Markdown when possible)

File Format Support

• Supported: XMind 2023 (Zen format), XMind 8 (Legacy format)
• Experimental: Earlier XMind versions may work but are untested

Error Recovery

• Invalid file paths: Validates before parsing; suggests checking file permissions
• Corrupted archives: Returns detailed error if .zip is invalid
• Missing nodes: Returns friendly error suggesting search_xmind_nodes for available IDs
• Large files: Suggests using search or branch extraction for better performance

Troubleshooting

Symptom	Likely cause	Fix
Error: Cannot find module '@modelcontextprotocol/sdk'	You ran node dist/index.js before building	Run npm install && npm run build
Claude Desktop doesn't list the three tools	Config path is wrong or node isn't on PATH	Re-check claude_desktop_config.json; the server only registers after a successful connect() on stdio
File not found: … from the CLI	~ not expanded on Windows shells	Pass an absolute path or use path.resolve upstream
nodeId returns "Node not found"	The id was from a different file or session	Re-run search_xmind_nodes against the same file — ids are file-scoped
Output blows past context window	Whole-document parse on a very large map	Use search_xmind_nodes first, then get_xmind_node_branch with a small depth
Failed to start MCP server on launch	Another process already bound the stdio	Close any duplicate launches; MCP over stdio is single-consumer
Corrupt archive errors	File isn't a real .xmind (renamed .zip, partial download)	Re-export from XMind; confirm unzip -l file.xmind lists content.xml or manifest.json

For anything not covered above, please open an issue (next section).

License

MIT License - See LICENSE file for details.

Support

For issues, feature requests, or questions:

1. Check existing issues at https://github.com/hhtczengjing/xmind-mcp/issues
2. Enable debug logging by setting DEBUG=xmind-mcp environment variable
3. Run the test suite to verify your install: npm test
4. When filing a new issue, include:
   • Output of node --version and npm --version
   • Exact command / tool call that failed and the full error text
   • A minimal .xmind sample (anonymized if it contains sensitive content)

Changelog

Version 1.0.0 (Initial Release)

• Full document parsing (Markdown and JSON formats)
• Node search with breadcrumb paths
• Branch extraction with depth limiting
• Support for Zen and Legacy XMind formats
• Token estimation and optimization suggestions
• Comprehensive error handling and logging
• MCP server integration for Claude and other clients