Skip to main content
Glama

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 --stdio

Clients 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 --version

Codex

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 = 120

Keep 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 list

If 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 xmind

Reopen 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_mind_map

Create a mind map from JSON topics

read_xmind_file

Read the first sheet's topic tree and statistics

analyze_mind_map

Analyze nodes, depth, and structure

convert_to_xmind

Convert a supported input file

list_xmind_files

List files by directory, pattern, and depth

translate_xmind_titles

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.xmind

After 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 -q

On 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

MIT

Available Tools

6 tools
analyze_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

    B3.4/5.0

    Scored across 6 tools

    Disambiguation4/5

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

    Naming Consistency5/5

    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.

    Tool Count5/5

    Six tools is well-scoped for a focused XMind manipulation server, covering reading, creating, converting, translating, analyzing, and listing without bloat.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to read and write XMind mind map files, allowing generation, editing, and analysis of mind maps directly in XMind.
      MIT