Xmindmcp

🚀 XMind AI MCP – Intelligent Mind Mapping Toolkit

A robust toolkit that can convert multiple formats to XMind, featuring AI analysis and a UVX-deployed MCP server. It effectively addresses the need for seamless multi - format conversion and intelligent mind - map analysis.

📝 Changelog

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

✨ Features

1. Universal File Converter

• Multi - format conversion: Convert Markdown, Text, HTML, Word, Excel to XMind.
• Smart detection: Automatically detect file types and structures.
• Batch processing: Convert multiple files simultaneously.
• Flexible output: Customize output paths and naming.

2. MCP Server (UVX)

• UVX - only deployment: No direct use of python or pip.
• IDE integration: Seamlessly integrate with Trae and MCP tools.
• Support for FastMCP and STDIO modes.

3. AI - Powered Analysis

• Structure analysis: Optimize the structure of mind maps.
• Topic suggestions: Provide AI - generated recommendations.
• Quality metrics: Conduct 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

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

💻 Usage Examples

Basic Usage

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"
})

Advanced Usage

The advanced usage mainly involves more complex configurations and batch operations. For example, when performing batch conversion, you can specify multiple file formats:

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

🖥️ Trae MCP Integration

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?)

⚙️ 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 are validated for conversion.
• Structure integrity is maintained.
• Content fidelity is preserved.
• XMind format compliance is ensured.

📄 License

This project is under the MIT License. See LICENSE for details.

🙏 Acknowledgments

• Thanks to the XMind team for providing an excellent mind - mapping tool.
• Thanks to the Trae IDE for offering a powerful development environment.
• Thanks to all contributors who have helped improve this project.