mind-map

This Mind Map MCP Server takes Markdown text and generates high-quality, watermark-free mind map PNG images. It supports both HTTP (networked) access and stdio-based MCP client interactions, enabling flexible deployment in both server and local development environments. Core capabilities include automatic content analysis to adjust the viewport, dynamic viewport scaling, high-DPI rendering, and optional multi-cloud storage integration. You can create mind maps from Markdown using create_mind_map, then list and retrieve previously generated images via list_images. The Docker deployment is recommended for quick setup, while uvx (Python) offers a clean local development workflow for stdio or HTTP modes. For storage, configure a chosen provider (local, S3, Azure, Google Cloud, etc.) to persist generated images and provide shareable URLs.

Prerequisites:

• Docker and docker-compose (recommended)
• Alternatively, Python 3.7+ and pip if you prefer uvx or local Python startup
• Optional: Node.js and markmap-cli if you plan to generate HTML previews locally

Method A: Docker Deployment (Recommended)

1. Ensure Docker and docker-compose are installed.
2. Clone the repository and navigate into the project directory, or pull the provided image as per your setup.
3. Start the service:

docker-compose up -d

4. Access endpoints (adjust host/ports if you customize):

• HTTP MCP Endpoint: http://localhost:8091/mcp
• Service Status: http://localhost:8091

5. Check service logs:

docker-compose logs -f

6. Stop the service:

docker-compose down

Method B: uvx Deployment (Python, recommended for Python environments)

1. Install uvx (if not already installed):

pip install uvx
# Or using pipx
pipx install uvx

2. Run the server (from the project directory):

uvx --from . python main.py stdio
# Or for HTTP/streamable mode
uvx --from . python main.py streamable-http --host 0.0.0.0 --port 8091

3. Access URLs (HTTP mode):

• HTTP MCP Endpoint: http://localhost:8091/mcp
• Service Status: http://localhost:8091

Method C: Local Installation (for development)

1. Install dependencies:

pip install -r requirements.txt
npm install -g markmap-cli
playwright install chromium

2. Run the server locally:

python main.py

3. Optional testing with MCP client using stdio or HTTP modes as configured in your environment.

Tips and common considerations:

• Deployment environment: Always adjust LOCAL_HOST and STORAGE configuration to reflect your server's reachable address. Using 127.0.0.1 will restrict access to the host machine.
• Storage configuration: Choose a storage provider suitable for your deployment (local for testing; cloud providers for production). Ensure required credentials are set in the environment (.env) or your deployment config.
• Docker recommended: The documentation emphasizes Docker deployment for ease and reliability; if you use docker-compose, ensure the port mappings align with your network policy.
• MCP endpoints: The MCP endpoint is typically at /mcp; ensure your firewall allows access to the configured port (default 8091).
• Image quality and rendering: You can tune output quality via the quality option in create_mind_map (low, medium, high, ultra) and adjust viewport/scale as needed for your display targets.
• Security: When exposing HTTP endpoints, consider securing with TLS termination, and validate inputs to prevent abuse.
• Troubleshooting: If images fail to generate, check Playwright and browser dependencies, ensure the storage backend is reachable, and verify that environment variables (e.g., STORAGE_TYPE and related keys) are correctly set.