XMind to Markdown MCP Server

将 XMind 思维导图文件转换为 Markdown 格式的 MCP (Model Context Protocol) 服务。

✨ 特性

• 🚀 快速转换：将 XMind 文件转换为结构化的 Markdown 文档
• 📊 保留层级：完整保留思维导图的层级结构
• 🏷️ 支持元数据：可选包含文件元信息（大小、时间等）
• 🔧 双工具支持：提供转换和结构查看两种工具
• 🌐 MCP 协议：标准化的 AI 工具接口，易于集成

📦 安装

使用 uvx（推荐）

uvx xmind-to-markdown-mcp

使用 pip

pip install xmind-to-markdown-mcp

🚀 快速开始

作为 MCP Server 使用

在支持 MCP 的客户端（如 Claude Desktop、Cursor、Cline）中配置：

{
  "mcpServers": {
    "xmind-to-markdown": {
      "command": "uvx",
      "args": ["xmind-to-markdown-mcp"]
    }
  }
}

可用工具

1. convert_xmind_to_markdown

将 XMind 文件转换为 Markdown 格式。

参数：

• xmind_path (必需): XMind 文件路径
• output_path (可选): 输出 Markdown 文件路径，不提供则自动保存到 output/ 目录
• include_metadata (可选): 是否包含文件元信息，默认 true

示例：

{
  "xmind_path": "/path/to/file.xmind",
  "output_path": "/path/to/output.md",
  "include_metadata": true
}

2. read_xmind_structure

读取并返回 XMind 文件的结构化数据（JSON 格式）。

参数：

• xmind_path (必需): XMind 文件路径

示例：

{
  "xmind_path": "/path/to/file.xmind"
}

📝 Markdown 转换格式

转换后的 Markdown 采用以下层级结构：

# [中心主题]

## [一级分支1]
- 子主题1.1
  - 详细内容1.1.1
  - 详细内容1.1.2
- 子主题1.2

## [一级分支2]
- 子主题2.1
  > 备注：这里是XMind中的备注内容
- 子主题2.2

---
**文件元信息**
- 文件名: example.xmind
- 文件大小: 15.32 KB
- 创建时间: 2025-01-01 10:00:00
- 修改时间: 2025-01-02 15:30:00

🔧 客户端配置示例

Claude Desktop (macOS)

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "xmind-to-markdown": {
      "command": "uvx",
      "args": ["xmind-to-markdown-mcp"]
    }
  }
}

Cursor IDE

在项目的 .vscode/settings.json 中添加：

{
  "mcp.servers": {
    "xmind-to-markdown": {
      "command": "uvx",
      "args": ["xmind-to-markdown-mcp"]
    }
  }
}

Cline (VS Code Extension)

在 Cline 的 MCP 设置中添加：

{
  "xmind-to-markdown": {
    "command": "uvx",
    "args": ["xmind-to-markdown-mcp"]
  }
}

🛠️ 开发

克隆仓库

git clone https://github.com/yourusername/xmind-to-markdown-mcp.git
cd xmind-to-markdown-mcp

安装开发依赖

pip install -e ".[dev]"

运行测试

pytest

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🤝 贡献

欢迎贡献！请随时提交 Pull Request。

📮 联系方式

• GitHub Issues: 提交问题
• Email: jiandong.yh@gmail.com

🙏 致谢

• FastMCP - MCP 服务框架
• xmindparser - XMind 文件解析库
• Model Context Protocol - MCP 协议规范