How to add Mindmap MCP Server to Windsurf
Convert Markdown content into interactive markmap-based mindmaps (HTML or saved file). Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.
Last updated June 14, 2026 · 234★ · stdio · no auth
Windsurf config for Mindmap MCP Server
uvx mindmap-mcp-server{
"mcpServers": {
"mindmap-mcp-server": {
"command": "uvx",
"args": [
"mindmap-mcp-server",
"--return-type",
"filePath"
]
}
}
}Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.
Setup steps
- 1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
- 2Paste the Mindmap MCP Server config below.
- 3Fill in placeholder secrets, then save.
- 4Click Refresh in the MCP panel.
- 5Mindmap MCP Server's tools become available to Cascade.
Before you start
- Node.js installed (required when running via the python or uvx commands)
- Python with uvx/pip, or Docker if using the container method
What Mindmap MCP Server can do in Windsurf
markdown-to-mindmap-contentConverts Markdown to an HTML mind map and returns the entire HTML content. Parameters: markdown (string, required) — the Markdown content to convert; toolbar (boolean, optional, default true) — whether to show the toolbar. Best for simple mind maps where HTML content size isn't a concern; previewable as an artifact in the AI client. (Documented for the Docker container.)
markdown-to-mindmap-fileConverts Markdown to an HTML mind map and saves it to a file in the mounted directory, returning the file path. Parameters: markdown (string, required) — the Markdown content to convert; filename (string, optional, default auto-generated timestamp name); toolbar (boolean, optional, default true). Best for complex mind maps or to save tokens for later use. (Documented for the Docker container.)
Security
When using the Docker method, you must mount a host directory to /output (e.g. -v /path/to/output/folder:/output) so generated mindmap files are written to a location you control. Docker needs permission to access that directory.
Mindmap MCP Server + Windsurf FAQ
Where is the Windsurf config file?
Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Mindmap MCP Server config there under the "mcpServers" key and restart the client.
Is Mindmap MCP Server safe to use with Windsurf?
When using the Docker method, you must mount a host directory to /output (e.g. -v /path/to/output/folder:/output) so generated mindmap files are written to a location you control. Docker needs permission to access that directory.
What return types are supported?
Two: html returns the entire HTML content of the mindmap (preview in your AI client's artifact), and filePath saves the mindmap to a file and returns the path, which saves tokens. With pip/uvx/python you select this via the --return-type flag; the Docker container exposes them as separate tools.
Does it require Node.js?
Yes. When running via the python or uvx commands, Node.js must be installed because the server uses the markmap-cli library.
What should Windows users do if npx has issues?
The README recommends the Docker method for Windows users experiencing issues, or alternatively using the VS Code 'Markmap' extension as a simpler solution.