How to Convert XMind Mind Maps to Markdown in CodeBuddy Using the MCP Tool – Step-by-Step Guide

Background and Goal

XMind excels at visual brainstorming, but Markdown is more searchable and editable in text editors and collaborative platforms. The goal is to convert an XMind file to a Markdown file (e.g., D:\test\test.md) while preserving both the graphical structure and the textual content.

Local MCP Service Setup

The conversion relies on a locally running MCP service whose configuration resides in c:\Users\admin\.codebuddy\mcp.json. The essential JSON fragment is:

{
  "mcpServers": {
    "xmind-to-markdown": {
      "type": "stdio",
      "command": "C:/Users/admin/AppData/Roaming/Python/Python314/Scripts/xmind-to-markdown-mcp.exe",
      "args": [],
      "env": { "PYTHONIOENCODING": "utf-8" },
      "description": "XMind 转 Markdown 转换工具"
    }
  }
}

The integration consists of four steps:

Install the conversion tool (Python package) – run pip install xmind-to-markdown-mcp, which creates the executable xmind-to-markdown-mcp.exe in the Python Scripts directory.

Write the MCP configuration file – create or edit mcp.json under C:\Users\admin\.codebuddy\, adding a new entry "xmind-to-markdown" under mcpServers.

Configure key fields type: "stdio" – CodeBuddy launches the exe as a subprocess via standard I/O. command – absolute path to the installed .exe; it must match the real location. env.PYTHONIOENCODING: "utf-8" – forces UTF‑8 encoding to avoid Chinese character garble. args: [] – no additional arguments are required.

Load and verify the service – after saving the config, restart or reload the MCP connection in CodeBuddy and ensure the xmind-to-markdown service is online, exposing the read_xmind_structure and convert_xmind_to_markdown commands.

Conversion Procedure

Switch CodeBuddy to Craft mode and enter the following command:

Convert D:\test\test.xmind to Markdown and save to D:/test/test.md

The resulting Markdown retains the hierarchical headings ( #, ##, ###, …) and outputs node text unchanged, matching the original mind‑map structure.

Issues Encountered

4.1 Chinese Encoding

The Windows default console encoding can cause UnicodeDecodeError. Setting PYTHONIOENCODING=utf-8 in the MCP config resolves this.

4.2 Path Escaping and Separators

JSON strings require double backslashes ( \\) or forward slashes ( /) for Windows paths. Mixing styles (e.g., D:\test/test.xmind) may lead to ambiguous parsing.

4.3 Common Causes of Service Startup Failure

Incorrect command path (mismatched Python version or install directory).

Missing Python package, resulting in absent executable.

JSON syntax errors in mcpServers (missing commas, mismatched quotes) that prevent the configuration from loading.

Conversion Results

Hierarchy retained – mind‑map nesting maps to Markdown heading levels.

Content complete – node text is output verbatim with indentation reflecting depth.

Best Practices

Run read_xmind_structure first to preview the source file.

After conversion, manually inspect key branches to ensure deep nodes are not lost.

Keep PYTHONIOENCODING=utf-8 in the environment to protect Chinese characters.

Use forward slashes or double backslashes consistently in source and target paths.

Verify that the target file is actually written to disk immediately after conversion.

Conclusion

By following the five steps – install the tool, configure mcp.json, reload the service, invoke the conversion, and verify the output – the xmind-to-markdown MCP service reliably transforms XMind mind maps into lossless Markdown. Pay special attention to the executable path, the UTF‑8 environment variable, and the actual file write‑out to ensure stable operation.