Xmind Mcp

xmind-mcp

An MCP (Model Context Protocol) server for reading and writing local XMind mind map files. XMind MCP exposes 27 tools that let any MCP-compatible AI client create, navigate, and edit .xmind files directly on disk.

------------------------------------------------------------------------

Prerequisites

Building

• Go 1.26.1 or later

Using

• Any MCP-compatible client (Claude Desktop, Cursor, etc.)

------------------------------------------------------------------------

Installation

Using go install (recommended)

go install github.com/mab-go/xmind-mcp/cmd/xmind-mcp@latest

This fetches, builds, and installs the binary in one step. No cloning required.

Build from source

git clone https://github.com/mab-go/xmind-mcp.git
cd xmind-mcp
make build

The binary is written to ./bin/xmind-mcp with version metadata from git (see the build target in the Makefile). A plain go build ./cmd/xmind-mcp also works but omits those ldflags.

> Note: A multi-platform container image is published to > GHCR on > each push to main and on version tags (see Docker below). Pre-built > binaries for Linux and Windows are attached to each tagged > GitHub Release.

------------------------------------------------------------------------

Docker

The image ghcr.io/mab-go/xmind-mcp runs the same stdio MCP server as the host binary. Mount a host directory that contains your .xmind files and pass paths as seen inside the container to the tools (for example, if you mount /home/you/maps at /maps, use /maps/my-map.xmind in tool calls).

Build and load locally (single platform):

docker buildx build --platform linux/amd64 --load -t xmind-mcp:test .

Optional build arguments (defaults match a local build without git in context):

docker buildx build \
  --platform linux/amd64 \
  --load \
  --build-arg VERSION="$(git describe --tags --always --dirty 2>/dev/null || echo dev)" \
  --build-arg COMMIT="$(git rev-parse HEAD 2>/dev/null || echo unknown)" \
  --build-arg DATE="$(date -u +%Y-%m-%d)" \
  -t xmind-mcp:test .

Multi-platform build (no --load; suitable for CI or registry push):

docker buildx build --platform linux/amd64,linux/arm64 .

Linux (amd64 host): Building the linux/arm64 variant runs RUN steps inside an ARM image. Without QEMU user emulation, those steps fail with exec format error. Install binfmt handlers once:

docker run --privileged --rm tonistiigi/binfmt --install all

Docker Desktop on macOS and Windows usually includes this. If you only need to check that the Dockerfile builds on your machine, use linux/amd64 only (the first command above).

Run interactively (stdio requires -i):

docker run --rm -i -v /path/on/host:/maps xmind-mcp:test --version

MCP client configuration (Docker)

For Claude Desktop, run the published image via docker and pass mounts in args (adjust the host path). Example claude_desktop_config.json:

{
  "mcpServers": {
    "xmind": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/on/host:/maps",
        "ghcr.io/mab-go/xmind-mcp:latest"
      ]
    }
  }
}

------------------------------------------------------------------------

MCP Client Configuration

Add the following to your MCP client's configuration file. For Claude Desktop, that's claude_desktop_config.json:

{
  "mcpServers": {
    "xmind": {
      "command": "xmind-mcp"
    }
  }
}

If you built from source or the binary is not on your PATH, use the full path to the binary:

{
  "mcpServers": {
    "xmind": {
      "command": "/absolute/path/to/xmind-mcp"
    }
  }
}

Log level

The server logs to standard error at info level by default. To change it, pass the --log-level flag or set the XMIND_MCP_LOG_LEVEL environment variable (the flag wins if both are set). Accepted values are debug, info, warn, and error; an unrecognized value exits with an error at startup.

debug adds per-connection lifecycle detail (the MCP initialize handshake). To enable it from a client config, set it via env:

{
  "mcpServers": {
    "xmind": {
      "command": "xmind-mcp",
      "env": { "XMIND_MCP_LOG_LEVEL": "debug" }
    }
  }
}

------------------------------------------------------------------------

Tools

All tools are prefixed with xmind_ to avoid collisions in multi-server environments.

Tier 1: File & Sheet Management

| Tool | Description | |----------------------------|------------------------------------------------------------------------------------------------| | xmind_open_map | Parse a .xmind file and return a structural summary (sheet names, root topics, node counts). | | xmind_list_sheets | Return the names and IDs of all sheets in a workbook. | | xmind_create_map | Create a new .xmind file with a single sheet and root topic. | | xmind_add_sheet | Add a new sheet to an existing workbook. | | xmind_delete_sheet | Remove a sheet from a workbook. | | xmind_list_relationships | List all relationships on a sheet (endpoint ids and topic titles as JSON). |

Tier 2: Finding Topics

Use these to resolve topic ids and titles before editing a specific branch of the tree. Some write tools instead need sheet-level ids or ids from xmind_list_relationships—see each tool's description.

| Tool | Description | |------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | xmind_get_subtree | Return the full topic hierarchy rooted at a given topic (or the whole sheet). | | xmind_get_topic_properties | Return one topic's metadata as JSON (notes, markers, boundaries, sheet relationships for that topic, child counts); use to verify writes. | | xmind_search_topics | Search for topics by keyword; returns matches with IDs, ancestryPath (titles from sheet root to parent of match, or null at sheet root), parent title, depth, and sheet fields when searching all sheets. | | xmind_find_topic | Find a single topic by exact title; returns ID, ancestryPath (sheet-root chain to parent of match; null at sheet root; not relative to parent_id scope), plus parent/sibling context relative to the search scope. |

Tier 3: Topic Mutations

Most tools here target a topic and take a topic_id from Tier 2 (or from prior results). A few use other ids (from_id/to_id, relationship_id, etc.)—see each row.

On success, xmind_add_topic, xmind_add_topics_bulk, xmind_duplicate_topic, and xmind_move_topic return JSON (topic ids, insertion indices, sibling counts, and related fields). Exact keys match each tool's description from the running MCP server. Other mutation tools in this tier return plain-text success messages unless their descriptions say otherwise.

| Tool | Description | |-----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | xmind_add_topic | Add a child under a parent; optional notes, labels, markers, link, remove_markers (same rules as xmind_set_topic_properties); success body is JSON. | | xmind_add_topics_bulk | Add many topics (flat or nested); each object may set the same optional metadata fields; success body is JSON. | | xmind_duplicate_topic | Deep-clone a topic subtree under another parent (same sheet); sheet relationships are not copied; success body is JSON. | | xmind_rename_topic | Change the title of an existing topic. | | xmind_delete_topic | Remove a topic and all its descendants. | | xmind_move_topic | Move a topic (and subtree) to a new parent; optional position sets insertion order (omit to append); success body is JSON. | | xmind_reorder_children | Change the order of a topic's children without reparenting. | | xmind_set_topic_properties | Set or update topic metadata (notes, labels, markers, link, remove_markers); clearing rules are on the tool. | | xmind_set_topic_properties_bulk | Apply the same metadata updates as xmind_set_topic_properties to many topic IDs in one read/write. | | xmind_add_floating_topic | Add a detached floating topic not connected to the main hierarchy. | | xmind_add_relationship | Draw a labeled connector between any two topics. | | xmind_delete_relationship | Remove a relationship by id (from xmind_list_relationships). | | xmind_add_summary | Add a summary callout bracketing a range of sibling topics. | | xmind_add_boundary | Add a visual boundary enclosure around all children of a topic. |

Tier 4: Utilities

| Tool | Description | |-----------------------------|------------------------------------------------------------------------| | xmind_flatten_to_outline | Export a sheet or subtree as indented plain text or Markdown. | | xmind_import_from_outline | Build a map or branch from an indented plain text or Markdown outline. | | xmind_find_and_replace | Rename topics matching a pattern across an entire sheet. |

------------------------------------------------------------------------

Development

First time only, install project-local tools (golangci-lint, goimports) into ./bin:

make setup

Then:

# Build (binary in ./bin/xmind-mcp), tests, and lint
make build test lint

# Run the server locally (stdio MCP)
make run

The primary test fixture is located at testdata/kitchen-sink.xmind. It exercises every supported XMind feature and should be used as the baseline for any handler development and testing. That file is stored in Git LFS; use a clone with LFS enabled (or run git lfs pull) before make test, or tests will fail on a pointer stub.

------------------------------------------------------------------------

License

MIT. See [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mab-go
• Source: mab-go/xmind-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.