XMind MCP Server: Read and Search Files

Overview

The XMind MCP Server provides a small, HTTP-based Model Context Protocol (MCP) service that exposes XMind files stored in a directory as searchable, machine-readable context for AI agents and developer tools. It indexes XMind (.xmind) files so you can run full-text and node-level searches, and retrieve structured content for use in prompts or downstream processing.

This server is useful when you need low-latency access to a corpus of mind maps for retrieval-augmented generation, context enrichment, or automated workflows. By implementing the MCP pattern (a lightweight protocol for tool/knowledge access), the service is straightforward to integrate into agent stacks, chatbots, or custom tooling that require deterministic access to file content.

Features

• Indexes XMind (.xmind) files from a configured directory
• Full-text search across map titles, node text, and notes
• Retrieve node-level or whole-file content in JSON
• HTTP endpoints compatible with MCP-style tool manifests
• Fast, incremental indexing for large file sets
• Basic metadata (filename, modification time, map id) exposed for file management

Installation / Configuration

1. Clone the project:

git clone https://github.com/apeyroux/mcp-xmind.git
cd mcp-xmind

2. Install dependencies and start (examples — actual commands may vary with your environment):

Node/npm example:

npm install
npm start
# or for development
npm run dev

Docker example:

# build
docker build -t mcp-xmind .
# run, exposing port 3333 and mounting local XMind directory into /data/xmind
docker run -p 3333:3333 -v /path/to/xmind:/data/xmind -e MCP_ROOT=/data/xmind mcp-xmind

Environment variables (common options):

# Directory containing .xmind files (required)
MCP_ROOT=/path/to/xmind

# HTTP port (default: 3333)
PORT=3333

# Reindex interval in seconds (optional)
REINDEX_INTERVAL=300

# Enable verbose logging (true/false)
LOG_LEVEL=info

After starting the server, you should have an HTTP API ready to accept search and read requests.

Available Tools / Available Resources

The server exposes two primary tools (endpoints) that map naturally to MCP tool definitions:

• xmind-search — search across all indexed XMind files and nodes
• xmind-read — read a specific file or node content as structured JSON

Example MCP manifest snippet (for an agent that consumes MCP-style tools):

{
  "schema_version": "0.1",
  "name_for_model": "xmind-tools",
  "description_for_model": "Search and read XMind mind maps",
  "tools": [
    {
      "name": "xmind-search",
      "description": "Run full-text search across XMind files. Query parameter: q",
      "mcp_url": "http://localhost:3333/search?q={q}"
    },
    {
      "name": "xmind-read",
      "description": "Retrieve file or node content by id or path. Use id or path parameter.",
      "mcp_url": "http://localhost:3333/read?id={id}&path={path}"
    }
  ]
}

Endpoints reference (typical routes):

Example cURL — search:

curl "http://localhost:3333/search?q=project%20roadmap&limit=10"

Example cURL — read by path:

curl "http://localhost:3333/read?path=teams/engineering.xmind"

Example cURL — read by id:

curl "http://localhost:3333/read?id=map-12345"

Response shapes are JSON objects with fields such as filename, mapId, nodeId (when applicable), title, content, and notes. Search responses include relevance scores and excerpts to help choose context for LLM prompts.

Use Cases

• Retrieval-augmented generation (RAG): Feed node-level content as context to an LLM prompt. For example, run a search for “deployment checklist” and include top node contents in the prompt to produce an action plan.
• Knowledge assistant for teams: Integrate with a chat agent so team members can ask “Where is the release plan?” and the agent uses xmind-search to return matching maps and nodes.
• Automated documentation: Periodically export selected nodes or whole maps to JSON or Markdown via xmind-read to generate structured documentation, release notes, or onboarding guides.
• Workflow automation: Trigger CI/CD or task-creation workflows when specific nodes appear or change (use the index metadata and modification time to detect updates).
• Audit and migration: Use the manifest and read endpoints to inventory a collection of mind maps and migrate content to other systems (wiki, issue tracker, knowledge base).

Tips for Developers

• Keep MCP_ROOT outside of the container image and mount it as a volume so maps can be updated without rebuilding.
• Tune the REINDEX_INTERVAL for your update frequency; shorter intervals increase freshness at the cost of more CPU/disk work.
• For large datasets, use the search limit and pagination support to avoid returning massive payloads.
• Combine search results with the read endpoint to fetch the full node payload only for the items you plan to include in prompts.

Further Reading and Source

• Source code and issues: https://github.com/apeyroux/mcp-xmind
• Model Context Protocol