MindManager MCP Server

Directory structure: └── mindm-mcp/ ├── README.md ├── LICENSE ├── pyproject.toml ├── update_version.py ├── examples/ │ └── test_server.py └── mindm_mcp/ ├── __init__.py └── server.py ================================================ File: README.md ================================================ # MindManager MCP Server A Model Context Protocol (MCP) server implementation for the `mindm` library, providing a standardized interface to interact with MindManager on Windows and macOS. [&style=for-the-badge&color=blue)](https://pypi.org/project/mindm-mcp/) [&style=for-the-badge&color=lightblue)](https://pypi.org/project/mindm/) ## Overview This server allows you to programmatically interact with MindManager through the Model Context Protocol (MCP), a standardized way to provide context and tools to LLMs. It leverages the `mindm` library to manipulate MindManager documents, topics, relationships, and other mindmap elements. Example:  ## Features - Retrieve mindmap structure and central topics - Export mindmaps to Mermaid, Markdown, JSON formats to be used in LLM chats - Get information about MindManager installation and library folders - Get current selection from MindManager ## Planned Features - Create new mindmaps from serialized data - Add, modify, and manipulate topics and subtopics - Add relationships between topics - Add tags to topics - Set document background images ## Requirements - Python 3.12 or higher - `mcp` package (Model Context Protocol SDK) - `mindm` library (included in this project) - MindManager (supported versions: 23-) installed on Windows or macOS ## Installation macOS ```bash # Clone the repository (if you're using it from a repository) git clone https://github.com/robertZaufall/mindm-mcp.git cd mindm-mcp # create a virtual environment for Python brew install uv # if needed uv pip install -r pyproject.toml # alternative: manual installation of modules uv add "mcp[cli]" uv add fastmcp uv add markdown-it-py uv add -U --index-url=https://test.pypi.org/simple/ --extra-index-url=https://pypi.org/simple/ mindm mindm-mcp ``` ## Installation Windows ```bash # Change to DOS command prompt cmd # Clone the repository (if you're using it from a repository) git clone https://github.com/robertZaufall/mindm-mcp.git cd mindm-mcp # create a virtual environment for Python pip install uv # if needed uv pip install -r pyproject.toml # install nodejs choco install nodejs # if you have chocolatey installed. If not install nodejs otherwise refreshenv node -v npm install -g npx ``` ## Usage ### MCP inspector ```bash # run mcp with inspector uv run --with mind --with fastmcp --with markdown-it-py mcp dev mindm_mcp/server.py ``` ### Claude Desktop #### Local python file Adjust the path for the local file as needed. ```json { "mcpServers": { "mindm (MindManager)": { "command": "uv", "args": [ "run", "--with", "mindm>=0.0.4.6", "--with", "fastmcp", "--with", "markdown-it-py", "/Users/master/git/mindm-mcp/mindm_mcp/server.py" ] } } } ``` #### Module from package repository Adjust `VIRTUAL_ENV` as needed. ```json { "mcpServers": { "mindm (MindManager)": { "command": "uv", "args": [ "run", "--with", "mindm>=0.0.4.6", "--with", "mindm-mcp>=0.0.1.50", "--with", "fastmcp", "--with", "markdown-it-py", "-m", "mindm_mcp.server" ], "env": { "VIRTUAL_ENV": "/Users/master/git/mindm-mcp/.venv" } } } } ``` Hint: If the MCP server does not show up with the hammer icon on Windows, close Claude Desktop and kill all background processes. ## MCP Tools The server exposes the following tools through the Model Context Protocol: ### Document Interaction - `get_mindmap`: Retrieves the current mindmap structure from MindManager - `get_selection`: Retrieves the currently selected topics in MindManager - `get_library_folder`: Gets the path to the MindManager library folder - `get_grounding_information`: Extracts grounding information (central topic, selected subtopics) from the mindmap ### Serialization - `serialize_current_mindmap_to_mermaid`: Serializes the currently loaded mindmap to Mermaid format - `serialize_current_mindmap_to_markdown`: Serializes the currently loaded mindmap to Markdown format - `serialize_current_mindmap_to_json`: Serializes the currently loaded mindmap to a detailed JSON object with ID mapping ## Platform Support - **Windows**: Full support for topics, notes, icons, images, tags, links, relationships, and RTF formatting - **macOS**: Support for topics, notes, and relationships (limited support compared to Windows) ## Integration with Claude and other LLMs This MCP server can be installed in Claude Desktop or other MCP-compatible applications, allowing LLMs to: 1. Access mindmap content 2. Manipulate mindmaps (coming) 3. Create new mindmaps based on LLM-generated content (coming) ## Troubleshooting - Ensure MindManager is running before starting the server - For macOS, make sure you allow Claude Desktop to automate MindManager ## Acknowledgements This project is built upon the `mindm` library, providing Python interfaces to MindManager on Windows and macOS platforms. It uses the Model Context Protocol (MCP) SDK developed by Anthropic. ## License MIT License - See LICENSE file for details ================================================ File: LICENSE ================================================ MIT License Copyright (c) [2025] [Robert Zaufall] Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ================================================ File: pyproject.toml ================================================ [build-system] requires = ["setuptools>=61.0"] build-backend = "setuptools.build_meta" [project] name = "mindm_mcp" version = "0.0.1.63" authors = [ { name="Robert Zaufall" }, ] description = "Model Context Protocol (MCP) server for the mindm library, enabling AI assistants like Claude to interact with MindManager." readme = "README.md" requires-python = ">=3.12" classifiers = [ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: Microsoft :: Windows", "Operating System :: MacOS :: MacOS X", ] dependencies = [ "mindm>=0.0.4.6", "uvicorn>=0.22.0", "aiohttp>=3.8.4", "pydantic>=1.10.7", "websockets>=10.4", "fastmcp>=0.4.1", "mcp[cli]>=1.6.0", "build>=1.2.2.post1", ] [project.urls] "Homepage" = "https://github.com/robertZaufall/mindm-mcp" "Bug Tracker" = "https://github.com/robertZaufall/mindm-mcp/issues" [project.scripts] mindm-mcp = "mindm_mcp.server:main" [tool.setuptools] packages = ["mindm_mcp"] ================================================ File: update_version.py ================================================ #!/usr/bin/env python3 import re # Read pyproject.toml with open("pyproject.toml", "r") as f: content = f.read() # Find version and update build number version_pattern = r'version = "([\d]+)\.([\d]+)\.([\d]+)\.([\d]+)"' version_match = re.search(version_pattern, content) if version_match: major, minor, patch, build = version_match.groups() new_build = str(int(build) + 1) new_version = f"{major}.{minor}.{patch}.{new_build}" new_content = re.sub(version_pattern, f'version = "{new_version}"', content) # Write updated content back with open("pyproject.toml", "w") as f: f.write(new_content) print(f"Updated version to {new_version}") else: print("Version pattern not found in pyproject.toml") ================================================ File: examples/test_server.py ================================================ import asyncio import json import sys import os from typing import Any, Dict, List, Union sys.path.append(os.path.abspath(os.path.join(os.path.dirname(__file__), '..'))) import mindm_mcp.server as server async def call_get_mindmap(): """Calls server.get_mindmap with different parameters.""" print("\n--- Testing get_mindmap ---") modes = ['full', 'content', 'text'] turbo_modes = [True, False] for mode in modes: for turbo_mode in turbo_modes: print(f"Calling get_mindmap(mode='{mode}', turbo_mode={turbo_mode})") result = await server.get_mindmap(mode=mode, turbo_mode=turbo_mode) print(f"Result: {json.dumps(result, indent=2)}") async def call_get_selection(): """Calls server.get_selection with different parameters.""" print("\n--- Testing get_selection ---") modes = ['full', 'content', 'text'] turbo_modes = [True, False] for mode in modes: for turbo_mode in turbo_modes: print(f"Calling get_selection(mode='{mode}', turbo_mode={turbo_mode})") result = await server.get_selection(mode=mode, turbo_mode=turbo_mode) print(f"Result: {json.dumps(result, indent=2)}") async def call_get_library_folder(): """Calls server.get_library_folder.""" print("\n--- Testing get_library_folder ---") print("Calling get_library_folder()") result = await server.get_library_folder() print(f"Result: {json.dumps(result, indent=2)}") async def call_get_grounding_information(): """Calls server.get_grounding_information with different parameters.""" print("\n--- Testing get_grounding_information ---") modes = ['full', 'content', 'text'] turbo_modes = [True, False] for mode in modes: for turbo_mode in turbo_modes: print(f"Calling get_grounding_information(mode='{mode}', turbo_mode={turbo_mode})") result = await server.get_grounding_information(mode=mode, turbo_mode=turbo_mode) print(f"Result: {json.dumps(result, indent=2)}") async def call_serialize_current_mindmap_to_mermaid(): """Calls server.serialize_current_mindmap_to_mermaid with different parameters.""" print("\n--- Testing serialize_current_mindmap_to_mermaid ---") id_only_options = [True, False] modes = ['full', 'content', 'text'] turbo_modes = [True, False] for id_only in id_only_options: for mode in modes: for turbo_mode in turbo_modes: print(f"Calling serialize_current_mindmap_to_mermaid(id_only={id_only}, mode='{mode}', turbo_mode={turbo_mode})") result = await server.serialize_current_mindmap_to_mermaid(id_only=id_only, mode=mode, turbo_mode=turbo_mode) print(f"Result: {json.dumps(result, indent=2)}") async def call_serialize_current_mindmap_to_markdown(): """Calls server.serialize_current_mindmap_to_markdown with different parameters.""" print("\n--- Testing serialize_current_mindmap_to_markdown ---") include_notes_options = [True, False] modes = ['full', 'content', 'text'] turbo_modes = [True, False] for include_notes in include_notes_options: for mode in modes: for turbo_mode in turbo_modes: print(f"Calling serialize_current_mindmap_to_markdown(include_notes={include_notes}, mode='{mode}', turbo_mode={turbo_mode})") result = await server.serialize_current_mindmap_to_markdown(include_notes=include_notes, mode=mode, turbo_mode=turbo_mode) print(f"Result: {json.dumps(result, indent=2)}") async def call_serialize_current_mindmap_to_json(): """Calls server.serialize_current_mindmap_to_json with different parameters.""" print("\n--- Testing serialize_current_mindmap_to_json ---") ignore_rtf_options = [True, False] modes = ['full', 'content', 'text'] turbo_modes = [True, False] for ignore_rtf in ignore_rtf_options: for mode in modes: for turbo_mode in turbo_modes: print(f"Calling serialize_current_mindmap_to_json(ignore_rtf={ignore_rtf}, mode='{mode}', turbo_mode={turbo_mode})") result = await server.serialize_current_mindmap_to_json(ignore_rtf=ignore_rtf, mode=mode, turbo_mode=turbo_mode) print(f"Result: {json.dumps(result, indent=2)}") async def main(): """Calls all the test functions.""" await call_get_mindmap() await call_get_selection() await call_get_library_folder() await call_get_grounding_information() await call_serialize_current_mindmap_to_mermaid() await call_serialize_current_mindmap_to_markdown() await call_serialize_current_mindmap_to_json() if __name__ == "__main__": # Check if MindManager is running before running the tests try: import mindm.mindmanager as mm server._get_library_folder() print("MindManager is running. Proceeding with tests.") asyncio.run(main()) except Exception as e: print(f"Error: MindManager is not running or an error occurred: {e}") print("Please ensure MindManager is running and try again.") sys.exit(1) ================================================ File: mindm_mcp/__init__.py ================================================ ================================================ File: mindm_mcp/server.py ================================================ #!/usr/bin/env python3 """ server.py - FastMCP implementation for the mindm library This module implements a Model Context Protocol (MCP) server for interacting with MindManager through the mindm library using FastMCP. """ import sys from typing import Dict, Any, List, Optional, Union from contextlib import asynccontextmanager from collections.abc import AsyncIterator from dataclasses import dataclass import asyncio import json from mcp.server.fastmcp import FastMCP, Context from mindmap.mindmap import MindmapDocument, MindmapTopic from mindmap import serialization, helpers import mindm from mindm import mindmanager as mm try: from importlib.metadata import version as _version __version__ = _version("mindm_mcp") except ImportError: __version__ = "unknown" # --- Globals --- # Initialize the MCP server mcp = FastMCP("mindm (MindManager)", version=__version__) doc_lock = asyncio.Lock() # --- Helper Functions --- def _serialize_result(data: Any) -> Union[Dict, List, str, int, float, bool, None]: """Helper to serialize results, especially MindmapTopic structures.""" if isinstance(data, (MindmapTopic, list)): # Use simple serialization for MCP results unless full detail is needed return serialization.serialize_object_simple(data) elif isinstance(data, tuple): # Tuples are often JSON serializable directly if elements are return list(data) # Convert to list for guaranteed JSON compatibility elif isinstance(data, (dict, str, int, float, bool, type(None))): return data else: # Attempt string conversion for unknown types print(f"Warning: Serializing unknown type {type(data)} as string.", file=sys.stderr) return str(data) def _handle_mindmanager_error(func_name: str, e: Exception) -> Dict[str, str]: """Formats MindManager errors for MCP response.""" error_message = f"Error during MindManager operation '{func_name}': {e}" print(f"ERROR: {error_message}", file=sys.stderr) # Check for specific known errors from mindm.mindmanager if possible if "No document found" in str(e): return {"error": "MindManager Error", "message": "No document found or MindManager not running."} # Add more specific error checks here based on mindm library return {"error": "MindManager Error", "message": f"An error occurred: {e}"} # --- Internal functions --- MACOS_ACCESS_METHOD = 'applescript' # appscript is not working with MCPs def _get_document_instance( charttype: str = 'auto', turbo_mode: bool = False, inline_editing_mode: bool = False, mermaid_mode: bool = True, macos_access: str = MACOS_ACCESS_METHOD ) -> MindmapDocument: document = MindmapDocument( charttype=charttype, turbo_mode=turbo_mode, inline_editing_mode=inline_editing_mode, mermaid_mode=mermaid_mode, macos_access=macos_access ) return document def _get_selection(mode='content', turbo_mode=False): document = _get_document_instance(turbo_mode=turbo_mode) if document.get_mindmap(mode=mode): selection = document.get_selection() return selection return None def _get_grounding_information(mode='text', turbo_mode=False): document = _get_document_instance(turbo_mode=True) if document.get_mindmap(mode=mode): document.get_selection() return document.get_grounding_information() return None def _get_mindmap_content(mode='content', turbo_mode=False): document = _get_document_instance(turbo_mode=turbo_mode) if document.get_mindmap(mode=mode): return document.mindmap return None def _serialize_mermaid(id_only=True, mode='content', turbo_mode=False): document = _get_document_instance(turbo_mode=turbo_mode) if document.get_mindmap(mode=mode): guid_mapping = {} serialization.build_mapping(document.mindmap, guid_mapping) mermaid = serialization.serialize_mindmap(document.mindmap, guid_mapping, id_only=id_only) return mermaid return None def _serialize_markdown(include_notes=True, mode='content', turbo_mode=False): document = _get_document_instance(turbo_mode=True) if document.get_mindmap(mode=mode): markdown = serialization.serialize_mindmap_markdown(document.mindmap, include_notes=include_notes) return markdown return None def _serialize_json(ignore_rtf=True, mode='content', turbo_mode=False): document = _get_document_instance(turbo_mode=turbo_mode) if document.get_mindmap(mode=mode): json_obj = serialization.serialize_object_simple(document.mindmap, ignore_rtf=ignore_rtf) return json_obj return None def _get_library_folder(): mindmanager_obj = mm.Mindmanager() library_folder = mindmanager_obj.get_library_folder() return library_folder # --- MCP Tools --- # == MindmapDocument Methods == @mcp.tool() async def get_mindmap( mode: str = 'full', turbo_mode: bool = False ) -> Dict[str, Any]: """ Retrieves the current mind map structure from MindManager. Args: mode (str): Detail level ('full', 'content', 'text'). Defaults to 'full'. turbo_mode (bool): Enable turbo mode (text only). Defaults to False. Returns: Dict[str, Any]: Serialized mind map structure or error dictionary. """ try: print(f"Calling get_mindmap(mode={mode}, turbo_mode={turbo_mode})", file=sys.stderr) mindmap = _get_mindmap_content(mode=mode, turbo_mode=turbo_mode) print("get_mindmap successful, returning serialized mindmap.", file=sys.stderr) return _serialize_result(mindmap) except Exception as e: return _handle_mindmanager_error("get_mindmap", e) @mcp.tool() async def get_selection( mode: str = 'full', turbo_mode: bool = False ) -> Union[List[Dict[str, Any]], Dict[str, str]]: """ Retrieves the currently selected topics in MindManager. Args: mode (str): Detail level ('full', 'content', 'text'). Defaults to 'full'. turbo_mode (bool): Enable turbo mode (text only). Defaults to False. Returns: Union[List[Dict[str, Any]], Dict[str, str]]: List of serialized selected topics or error dictionary. """ try: print(f"Calling get_selection(mode={mode}, turbo_mode={turbo_mode})", file=sys.stderr) selection = _get_selection(mode=mode, turbo_mode=turbo_mode) print("get_selection successful, returning serialized selection.", file=sys.stderr) return _serialize_result(selection) except Exception as e: return _handle_mindmanager_error("get_selection", e) @mcp.tool() async def get_library_folder( ) -> Union[str, Dict[str, str]]: """ Gets the path to the MindManager library folder. Returns: Union[str, Dict[str, str]]: The library folder path or error dictionary. """ try: folder_path = _get_library_folder() print(f"get_library_folder() returned: {folder_path}", file=sys.stderr) return folder_path except Exception as e: return _handle_mindmanager_error("get_library_folder", e) @mcp.tool() async def get_mindmanager_version( ) -> Union[str, Dict[str, str]]: """ Gets the version of the MindManager application. Returns: Union[str, Dict[str, str]]: The version of the MindManager application or error dictionary. """ try: version = mm.Mindmanager().get_version() print(f"get_mindmanager_version() returned: {version}", file=sys.stderr) return version except Exception as e: return _handle_mindmanager_error("get_mindmanager_version", e) @mcp.tool() async def get_grounding_information( mode: str = 'full', turbo_mode: bool = False ) -> Union[List[str], Dict[str, str]]: """ Extracts grounding information (central topic, selected subtopics) from the mindmap. Args: mode (str): Detail level ('full', 'content', 'text'). Defaults to 'full'. turbo_mode (bool): Enable turbo mode (text only). Defaults to False. Returns: Union[List[str], Dict[str, str]]: A list containing [top_most_topic, subtopics_string] or error dictionary. """ try: print("Calling get_grounding_information()", file=sys.stderr) top_most, subtopics_str = _get_grounding_information(mode=mode, turbo_mode=turbo_mode) print(f"get_grounding_information() returned: top='{top_most}', subtopics='{subtopics_str}'", file=sys.stderr) return [top_most, subtopics_str] # Return as list for JSON except Exception as e: # This function doesn't directly call MindManager, so errors are less likely external print(f"ERROR in get_grounding_information: {e}", file=sys.stderr) return {"error": "Internal Error", "message": f"Failed to get grounding information: {e}"} # == Serialization Methods (Operating on current in-memory mindmap) == @mcp.tool() async def serialize_current_mindmap_to_mermaid( id_only: bool = False, mode: str = 'full', turbo_mode: bool = False ) -> Union[str, Dict[str, str]]: """ Serializes the currently loaded mindmap to Mermaid format. Args: id_only (bool): If True, only include IDs without detailed attributes. Defaults to False. mode (str): Detail level ('full', 'content', 'text'). Defaults to 'full'. turbo_mode (bool): Enable turbo mode (text only). Defaults to False. Returns: Union[str, Dict[str, str]]: Mermaid formatted string or error dictionary. """ try: print(f"Serializing current mindmap to Mermaid (id_only={id_only}).", file=sys.stderr) text = _serialize_mermaid(id_only=id_only, mode=mode, turbo_mode=turbo_mode) print("Serialization to Mermaid successful.", file=sys.stderr) return text except Exception as e: print(f"ERROR during serialization to Mermaid: {e}", file=sys.stderr) return {"error": "Serialization Error", "message": f"Failed to serialize to Mermaid: {e}"} @mcp.tool() async def serialize_current_mindmap_to_markdown( include_notes: bool = True, mode: str = 'content', turbo_mode: bool = False ) -> Union[str, Dict[str, str]]: """ Serializes the currently loaded mindmap to Markdown format. Args: include_notes (bool): If True, include notes in the serialization. Defaults to True. mode (str): Detail level ('full', 'content', 'text'). Defaults to 'full'. turbo_mode (bool): Enable turbo mode (text only). Defaults to False. Returns: Union[str, Dict[str, str]]: Markdown formatted string or error dictionary. """ try: print(f"Serializing current mindmap to Markdown.", file=sys.stderr) text = _serialize_markdown(include_notes=include_notes, mode=mode, turbo_mode=turbo_mode) print("Serialization to Markdown successful.", file=sys.stderr) return text except Exception as e: print(f"ERROR during serialization to Markdown: {e}", file=sys.stderr) return {"error": "Serialization Error", "message": f"Failed to serialize to Markdown: {e}"} @mcp.tool() async def serialize_current_mindmap_to_json( ignore_rtf: bool = True, mode: str = 'content', turbo_mode: bool = True ) -> Union[Dict[str, Any], Dict[str, str]]: """ Serializes the currently loaded mindmap to a detailed JSON object with ID mapping. Args: ignore_rtf (bool): Whether to ignore RTF content. Defaults to True. mode (str): Detail level ('full', 'content', 'text'). Defaults to 'full'. turbo_mode (bool): Enable turbo mode (text only). Defaults to False. Returns: Union[Dict[str, Any], Dict[str, str]]: JSON serializable dictionary or error dictionary. """ try: print(f"Serializing current mindmap to detailed JSON (ignore_rtf={ignore_rtf}).", file=sys.stderr) json_obj = _serialize_json(ignore_rtf=ignore_rtf, mode=mode, turbo_mode=turbo_mode) print("Serialization to detailed JSON successful.", file=sys.stderr) return json_obj except Exception as e: print(f"ERROR during serialization to JSON: {e}", file=sys.stderr) return {"error": "Serialization Error", "message": f"Failed to serialize to JSON: {e}"} @mcp.tool() async def get_versions() -> Dict[str, str]: """ Get the versions of the MindManager Automation MCP Server components. Returns: Dict[str, str]: A dictionary containing the versions of the components. """ result = {} result["mindm-mcp"] = __version__ result["mindm"] = mindm.__version__ return result def main(): print("Starting MindManager Automation MCP Server...", file=sys.stderr) try: mcp.run(transport='stdio') except Exception as main_e: print(f"FATAL: Server crashed: {main_e}", file=sys.stderr) sys.exit(1) finally: print("MindManager Automation MCP Server stopped.", file=sys.stderr) # --- Main Execution --- if __name__ == "__main__": main()