🧠 XMind AI MCP – Intelligent Mind Mapping Toolkit

A robust toolkit for converting multiple formats to XMind, with AI analysis and a UVX-deployed MCP server.

Changelog

1.3.1: Fix analyze_mind_map compatibility with new read structure (no data.structure).

🚀 Core Features

1. Universal File Converter

Multi-format conversion: Markdown, Text, HTML, Word, Excel → XMind
Smart detection: Auto-detect file types and structure
Batch processing: Convert multiple files at once
Flexible output: Custom output paths and naming

2. MCP Server (UVX)

UVX-only deployment: no direct python or pip
IDE integration: Works seamlessly with Trae and MCP tools
FastMCP and STDIO modes supported

3. AI-Powered Analysis

Structure analysis: Optimize mind map structure
Topic suggestions: AI-generated recommendations
Quality metrics: Comprehensive assessment and validation

📁 Project Structure

XmindMcp/
├── configs/                      # MCP server config
├── docs/                         # Documentation and guides
├── examples/                     # Sample inputs
├── output/                       # Generated XMind files
├── tests/                        # Test suite
├── universal_xmind_converter.py  # Standalone converter CLI
├── xmind_core_engine.py          # Core engine
├── xmind_mcp_server.py           # MCP server (FastMCP / STDIO)
├── xmind_mcp/                    # Package entry (`xmind-mcp`)
│   ├── __init__.py
│   └── __main__.py
└── configs/mcp_config.json       # MCP server configuration (env only)

🔄 Architecture Overview

graph TD
    User([User]) -->|CLI| Converter[universal_xmind_converter.py]
    User -->|MCP| MCP[xmind_mcp_server.py]
    User -->|Tests| TestRunner[tests/run_all_tests.py]

    MCP -->|Tools| Core[xmind_core_engine.py]
    Core -->|Convert| Converter
    Core -->|Validate| Validator[validate_xmind_structure.py]
    Core -->|AI| AIExt[xmind_ai_extensions.py]

    Converter -->|Read| Examples[examples/]
    Converter -->|Write| Output[output/]

    classDef userLayer fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef serverLayer fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef engineLayer fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    classDef fileLayer fill:#fce4ec,stroke:#880e4f,stroke-width:2px

    class User,TestRunner userLayer
    class MCP serverLayer
    class Core,AIExt engineLayer
    class Examples,Output fileLayer

🔧 Quick Start (UVX)

Install UV (if not installed)

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Run (published package)

uvx xmind-mcp --mode fastmcp
uvx xmind-mcp --version
uvx xmind-mcp --help

Local development (in repo root)

uvx --from . xmind-mcp --mode fastmcp
# Fallback (STDIO)
uvx xmind-mcp --stdio

🖥️ Trae MCP Integration (UVX)

Standard configuration (recommended)

{
  "mcpServers": {
    "xmind-mcp": {
      "command": "uvx",
      "args": ["xmind-mcp"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUTF8": "1"
      },
      "description": "XMind MCP - UVX installed",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Local development configuration (no absolute paths)

{
  "mcpServers": {
    "xmind-mcp": {
      "command": "uvx",
      "args": ["--from", ".", "xmind-mcp"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUTF8": "1"
      },
      "description": "XMind MCP - local development",
      "disabled": false,
      "autoApprove": []
    }
  }
}

📦 Standalone Conversion (CLI)

Single file

python universal_xmind_converter.py examples/test_markdown.md
python universal_xmind_converter.py examples/test_document.docx --output output/my_mind_map.xmind

Batch conversion

python universal_xmind_converter.py examples/ --batch
python universal_xmind_converter.py examples/ --batch --format markdown,html,txt

🛠️ Available MCP Tools

read_xmind_file(file_path) – read XMind content
create_mind_map(title, topics_json, output_path?) – create a new map
analyze_mind_map(file_path) – analyze structure and metrics
convert_to_xmind(source_filepath, output_filepath?) – convert files to XMind
list_xmind_files(directory?, recursive?) – list XMind files
translate_xmind_titles(source_filepath, output_filepath?, target_lang?, overwrite?)

✅ Usage Examples (Trae MCP)

Convert a Markdown file

convert_to_xmind({
  "source_filepath": "examples/test_markdown.md"
  # omit output_filepath to use the server's default absolute output directory (if configured)
})

Create a mind map (use default_output_dir in config)

create_mind_map({
  "title": "Project Plan",
  "topics_json": [{"title": "Milestone 1"}, {"title": "Milestone 2"}]
  # do not pass output_path if a default absolute output directory is configured
})

Analyze an existing map

analyze_mind_map({
  "file_path": "output/test_markdown.xmind"
})

⚙️ Paths & Configuration

Examples in docs use project-relative paths for readability.
For MCP output tools, configure a default absolute output directory via MCP config env (configs/mcp_config.json) or CLI --default-output-dir.
If no default is configured, pass an explicit absolute output_path/output_filepath in tool calls; relative paths are rejected by MCP output tools.

🧪 Run Tests

python tests/run_all_tests.py
python tests/run_all_tests.py --english
python tests/test_setup.py
python tests/test_core.py

📖 Documentation

docs/TRAE_MCP_SETUP.md – IDE MCP configuration
docs/UNIVERSAL_CONVERTER_USAGE.md – standalone converter usage
docs/xmind_ai_mcp_design.md – architecture and design

🎨 Supported Formats

Markdown (.md, .markdown)
Text (.txt, .text)
HTML (.html, .htm)
Word (.docx)
Excel (.xlsx)
CSV (.csv)
JSON (.json)
XML (.xml)
YAML (.yaml, .yml)

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Commit (git commit -m "feat: add your feature")
Push (git push origin feature/your-feature)
Open a Pull Request

🔍 Validation & Quality

9 file formats validated for conversion
Structure integrity maintained
Content fidelity preserved
XMind format compliance ensured

📝 License

MIT License – see LICENSE for details.

🙏 Acknowledgments

XMind team for the excellent mind mapping tool
Trae IDE for the powerful development environment
All contributors who helped improve this project

🧠 XMind AI MCP – Intelligent Mind Mapping Toolkit

A robust toolkit for converting multiple formats to XMind, with AI analysis and a UVX-deployed MCP server.

Changelog

1.3.1: Fix analyze_mind_map compatibility with new read structure (no data.structure).

🚀 Core Features

1. Universal File Converter

Multi-format conversion: Markdown, Text, HTML, Word, Excel → XMind
Smart detection: Auto-detect file types and structure
Batch processing: Convert multiple files at once
Flexible output: Custom output paths and naming

2. MCP Server (UVX)

UVX-only deployment: no direct python or pip
IDE integration: Works seamlessly with Trae and MCP tools
FastMCP and STDIO modes supported

3. AI-Powered Analysis

Structure analysis: Optimize mind map structure
Topic suggestions: AI-generated recommendations
Quality metrics: Comprehensive assessment and validation

📁 Project Structure

XmindMcp/
├── configs/                      # MCP server config
├── docs/                         # Documentation and guides
├── examples/                     # Sample inputs
├── output/                       # Generated XMind files
├── tests/                        # Test suite
├── universal_xmind_converter.py  # Standalone converter CLI
├── xmind_core_engine.py          # Core engine
├── xmind_mcp_server.py           # MCP server (FastMCP / STDIO)
├── xmind_mcp/                    # Package entry (`xmind-mcp`)
│   ├── __init__.py
│   └── __main__.py
└── configs/mcp_config.json       # MCP server configuration (env only)

🔄 Architecture Overview

graph TD
    User([User]) -->|CLI| Converter[universal_xmind_converter.py]
    User -->|MCP| MCP[xmind_mcp_server.py]
    User -->|Tests| TestRunner[tests/run_all_tests.py]

    MCP -->|Tools| Core[xmind_core_engine.py]
    Core -->|Convert| Converter
    Core -->|Validate| Validator[validate_xmind_structure.py]
    Core -->|AI| AIExt[xmind_ai_extensions.py]

    Converter -->|Read| Examples[examples/]
    Converter -->|Write| Output[output/]

    classDef userLayer fill:#e1f5fe,stroke:#01579b,stroke-width:2px
    classDef serverLayer fill:#f3e5f5,stroke:#4a148c,stroke-width:2px
    classDef engineLayer fill:#e8f5e8,stroke:#1b5e20,stroke-width:2px
    classDef fileLayer fill:#fce4ec,stroke:#880e4f,stroke-width:2px

    class User,TestRunner userLayer
    class MCP serverLayer
    class Core,AIExt engineLayer
    class Examples,Output fileLayer

🔧 Quick Start (UVX)

Install UV (if not installed)

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Run (published package)

uvx xmind-mcp --mode fastmcp
uvx xmind-mcp --version
uvx xmind-mcp --help

Local development (in repo root)

uvx --from . xmind-mcp --mode fastmcp
# Fallback (STDIO)
uvx xmind-mcp --stdio

🖥️ Trae MCP Integration (UVX)

Standard configuration (recommended)

{
  "mcpServers": {
    "xmind-mcp": {
      "command": "uvx",
      "args": ["xmind-mcp"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUTF8": "1"
      },
      "description": "XMind MCP - UVX installed",
      "disabled": false,
      "autoApprove": []
    }
  }
}

Local development configuration (no absolute paths)

{
  "mcpServers": {
    "xmind-mcp": {
      "command": "uvx",
      "args": ["--from", ".", "xmind-mcp"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUTF8": "1"
      },
      "description": "XMind MCP - local development",
      "disabled": false,
      "autoApprove": []
    }
  }
}

📦 Standalone Conversion (CLI)

Single file

python universal_xmind_converter.py examples/test_markdown.md
python universal_xmind_converter.py examples/test_document.docx --output output/my_mind_map.xmind

Batch conversion

python universal_xmind_converter.py examples/ --batch
python universal_xmind_converter.py examples/ --batch --format markdown,html,txt

🛠️ Available MCP Tools

read_xmind_file(file_path) – read XMind content
create_mind_map(title, topics_json, output_path?) – create a new map
analyze_mind_map(file_path) – analyze structure and metrics
convert_to_xmind(source_filepath, output_filepath?) – convert files to XMind
list_xmind_files(directory?, recursive?) – list XMind files
translate_xmind_titles(source_filepath, output_filepath?, target_lang?, overwrite?)

✅ Usage Examples (Trae MCP)

Convert a Markdown file

convert_to_xmind({
  "source_filepath": "examples/test_markdown.md"
  # omit output_filepath to use the server's default absolute output directory (if configured)
})

Create a mind map (use default_output_dir in config)

create_mind_map({
  "title": "Project Plan",
  "topics_json": [{"title": "Milestone 1"}, {"title": "Milestone 2"}]
  # do not pass output_path if a default absolute output directory is configured
})

Analyze an existing map

analyze_mind_map({
  "file_path": "output/test_markdown.xmind"
})

⚙️ Paths & Configuration

Examples in docs use project-relative paths for readability.
For MCP output tools, configure a default absolute output directory via MCP config env (configs/mcp_config.json) or CLI --default-output-dir.
If no default is configured, pass an explicit absolute output_path/output_filepath in tool calls; relative paths are rejected by MCP output tools.

🧪 Run Tests

python tests/run_all_tests.py
python tests/run_all_tests.py --english
python tests/test_setup.py
python tests/test_core.py

📖 Documentation

docs/TRAE_MCP_SETUP.md – IDE MCP configuration
docs/UNIVERSAL_CONVERTER_USAGE.md – standalone converter usage
docs/xmind_ai_mcp_design.md – architecture and design

🎨 Supported Formats

Markdown (.md, .markdown)
Text (.txt, .text)
HTML (.html, .htm)
Word (.docx)
Excel (.xlsx)
CSV (.csv)
JSON (.json)
XML (.xml)
YAML (.yaml, .yml)

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/your-feature)
Commit (git commit -m "feat: add your feature")
Push (git push origin feature/your-feature)
Open a Pull Request

🔍 Validation & Quality

9 file formats validated for conversion
Structure integrity maintained
Content fidelity preserved
XMind format compliance ensured

📝 License

MIT License – see LICENSE for details.

🙏 Acknowledgments

XMind team for the excellent mind mapping tool
Trae IDE for the powerful development environment
All contributors who helped improve this project