XMind AI MCP
Converts Markdown files to XMind mind map format, with support for structure detection and batch processing.
Uses Mermaid diagrams in documentation to visualize the architecture and data flow of the XMind conversion system.
Provides Python-based tools for creating, analyzing, and converting multiple file formats to XMind mind maps with AI-powered structure analysis.
Converts XML files to XMind mind map format with structure preservation.
Converts YAML files to XMind mind map format with structure detection.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@XMind AI MCP convert my meeting notes from markdown to a mind map"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
XMind MCP
Convert Markdown, text outlines, HTML, Word, and Excel to XMind. MCP tools provide mind map creation, reading, structural analysis, conversion, file listing, and title translation.
中文 · Documentation index (Chinese)
Quick start
Requires UV and Python 3.11+. From the repository root, run the current source:
uvx --python 3.12 --from . xmind-mcp --stdioClients communicate through standard input/output. Waiting for input in a terminal is normal. uvx xmind-mcp installs the published package and does not include unpublished local changes.
The project uses MCP Python SDK v2, supporting the 2026-07-28 protocol revision and legacy initialization. --mode fastmcp, --mode stdio, and --stdio remain aliases for the same STDIO entry point.
See the usage guide for MCP client configuration and path rules.
Related MCP server: Markmap MCP Server
Agent setup
These examples use PyPI version 2.0.1; cloning this repository is unnecessary. Install UV and check that uvx --version works. The first run needs network access to download dependencies. You can install them and check the package version first:
uvx --python 3.12 --from xmind-mcp==2.0.1 xmind-mcp --versionCodex
Merge the TOML example into ~/.codex/config.toml, or .codex/config.toml in a trusted project:
[mcp_servers.xmind]
command = "uvx"
args = ["--python", "3.12", "--from", "xmind-mcp==2.0.1", "xmind-mcp", "--stdio"]
startup_timeout_sec = 120
tool_timeout_sec = 120Keep other settings. Update an existing [mcp_servers.xmind] table rather than adding it twice. Restart the client and start a new session. Alternatively, register through the CLI:
codex mcp add xmind -- uvx --python 3.12 --from xmind-mcp==2.0.1 xmind-mcp --stdio
codex mcp listIf the initial startup times out after CLI registration, set startup_timeout_sec as shown above. Desktop, CLI, and IDE clients share the same host's configuration. Use /mcp in the CLI TUI to inspect connections. Official Codex documentation
Claude Code
Register a user-scoped server for use across projects:
claude mcp add --transport stdio --scope user xmind -- uvx --python 3.12 --from xmind-mcp==2.0.1 xmind-mcp --stdio
claude mcp get xmindReopen Claude Code and run /mcp in the session to check the connection. For team project configuration, replace --scope user with --scope project, which writes .mcp.json in the project root. You can also merge the JSON example into that file. Approve project servers when the client prompts. Official Claude Code documentation
Cursor
Merge the JSON example into ~/.cursor/mcp.json for all projects, or .cursor/mcp.json inside one project:
{
"mcpServers": {
"xmind": {
"command": "uvx",
"args": ["--python", "3.12", "--from", "xmind-mcp==2.0.1", "xmind-mcp", "--stdio"]
}
}
}Keep other entries under mcpServers. Save and reload the client, check xmind in MCP settings, then use it in Agent chat. A project entry takes priority over a global entry with the same name. Official Cursor documentation
Verify and customize
Once connected, six tools should be available. Try this in your agent:
Use xmind to create a development plan covering requirements, implementation, testing, and release. Save it to the default directory and return a file link.
Output defaults to Documents/XmindOutput inside the process user's home directory, such as /Users/username/Documents/XmindOutput on macOS or C:/Users/username/Documents/XmindOutput on Windows. Missing directories are created automatically. Successful create, convert, and translate tools return data.absolute_path.
No env is needed; MCP communication uses UTF-8. If the client cannot find uvx, run command -v uvx on macOS/Linux or where.exe uvx on Windows and use the absolute executable path as command. In configuration locations above, ~ means your home directory, typically %USERPROFILE% on Windows.
To override output, append "--default-output-dir", "/absolute/path/to/output" to args. Use forward slashes such as D:/XmindOutput in Windows JSON/TOML strings. For local development, replace the package specifier after --from with the repository's absolute path. Other STDIO clients using mcpServers can reuse the JSON example; consult their documentation for the configuration location.
Six MCP tools
Tool | Purpose |
| Create a mind map from JSON topics |
| Read the first sheet's topic tree and statistics |
| Analyze nodes, depth, and structure |
| Convert a supported input file |
| List files by directory, pattern, and depth |
| Translate titles through an external provider |
Topic input uses title and children, with legacy aliases supported. From 2.0.1, output defaults to Documents/XmindOutput inside the current user’s home directory, created automatically. Override it with --default-output-dir or XMIND_MCP_DEFAULT_OUTPUT_DIR, or pass an explicit absolute file path. Successful create, convert, and translate tools return data.absolute_path. Translation requires network access; optional AI helpers are separate from the six registered tools.
Standalone conversion
uv run xmind-convert examples/test_markdown.md output/markdown.xmindAfter installation, xmind-convert input.md output/result.xmind is also available. Supported inputs are Markdown, TXT, HTML, .docx, and .xlsx; see the usage guide for parsing rules.
Development
uv venv --python 3.12
uv pip install -e '.[test]'
.venv/bin/python tests/run_all_tests.py -qOn Windows, use .venv/Scripts/python.exe instead of .venv/bin/python.
Branch pushes and pull requests run automated checks. Successful checks on main automatically increment the patch version and publish to PyPI. Configure PYPI_API_TOKEN once; see the development guide.
Documentation
Usage guide: setup, MCP configuration, arguments, conversion, and troubleshooting.
Architecture: models, service boundaries, configuration isolation and extensions.
Development and publishing: environments, tests, distribution checks, versions, and PyPI releases.
Implementation and MCP entry points live in xmind_mcp/; root-level scripts and their import APIs have been removed. See the documentation index for the consolidation map.
License
Available Tools
6 toolsanalyze_mind_mapC
分析思维导图结构,返回节点数量、层级及结构建议。
Inputs: file_path (required). Returns: result
convert_to_xmindA
将TXT、Markdown、HTML、Word、Excel转换为XMind。源路径必须为绝对路径;source_file/output_file 是旧参数别名。JSON主题请用 create_mind_map。
Inputs: output_file, source_file, output_filepath, source_filepath. Returns: result
create_mind_mapC
创建思维导图。topics_json 为主题JSON字符串,支持 children/topics/subtopics/nodes/items 别名;output_path 为可选绝对输出路径。
Inputs: title (required), topics_json (required), output_path. Returns: result
list_xmind_filesA
列出XMind文件。directory 为绝对目录,省略时使用默认输出目录;支持递归、文件名模式和最大搜索深度。
Inputs: pattern, directory, max_depth, recursive. Returns: result
read_xmind_fileC
读取XMind文件内容(返回结构与统计信息)。file_path 为XMind文件路径。
Inputs: file_path (required). Returns: result
translate_xmind_titlesB
翻译XMind标题并输出新文件。output_filepath 为可选绝对输出路径;target_lang 默认为 en,覆盖已有文件需 overwrite=True。
Inputs: source_filepath (required), overwrite, target_lang, output_filepath. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools have distinct verbs (read, translate, create, analyze, convert, list). However, create_mind_map and convert_to_xmind both produce XMind files, and read_xmind_file vs analyze_mind_map both inspect file contents, so descriptions must disambiguate (they do, e.g. explicitly routing JSON topics to create_mind_map).
Every tool follows a clean verb_noun snake_case pattern: read_xmind_file, translate_xmind_titles, create_mind_map, analyze_mind_map, convert_to_xmind, list_xmind_files. No stylistic deviations.
Six tools is well-scoped for a focused XMind manipulation server, covering reading, creating, converting, translating, analyzing, and listing without bloat.
Core lifecycle (read, create, convert, list) is covered, but there is no tool to update/edit existing mind map nodes in place and no delete/rename operation for files. Translating and analyzing partly fill gaps, but agents editing an existing map hit a dead end.
Maintenance
Related MCP Connectors
Mind maps with a full document in every node. Read, search and edit your maps from AI tools.
Create mindmaps of any topic from Claude, Cursor or any AI agent. Every node can be an AI chat.
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
AI-powered diagrams, mind maps, flowcharts on a free unlimited collaborative whiteboard
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables conversion of plain text descriptions and Markdown content into interactive mind maps using AI. Automatically uploads generated mind maps to Aliyun OSS and provides online access links.48 npm1MIT
- AlicenseNot gradedqualityDmaintenanceConverts Markdown text into interactive mind maps, supporting export as PNG, JPG, and SVG images.15 npm5MIT
- AlicenseAqualityDmaintenanceConverts XMind mind map files into structured Markdown documents, preserving hierarchy and optionally including metadata.22MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to read and write XMind mind map files, allowing generation, editing, and analysis of mind maps directly in XMind.MIT