How to add Claude Mermaid MCP Server to Windsurf

Render Mermaid diagrams in Claude Code with live-reload browser preview and SVG/PNG/PDF export. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 170★ · stdio · no auth

Windsurf config for Claude Mermaid MCP Server

npm install -g claude-mermaid

{
  "mcpServers": {
    "claude-mermaid-mcp-server": {
      "command": "claude-mermaid",
      "args": []
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Claude Mermaid MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Claude Mermaid MCP Server's tools become available to Cascade.

Before you start

Node.js with npm (for global install via 'npm install -g claude-mermaid')
An MCP-compatible client (Claude Code, Codex, Cursor, Cline, Windsurf, or Gemini CLI)
A web browser for viewing live previews

What Claude Mermaid MCP Server can do in Windsurf

mermaid_preview

Render and open a live preview of a Mermaid diagram. Params: diagram (string, required), preview_id (string, required — identifies the preview session for concurrent diagrams), format (svg|png|pdf, default svg; live preview only for svg), theme (default|forest|dark|neutral, default default), background (default white), width (default 800), height (default 600), scale (default 2).

mermaid_save

Save the current live diagram to a path. Params: save_path (string, required — e.g. ./docs/diagram.svg), preview_id (string, required — must match the one used in mermaid_preview), format (svg|png|pdf, default svg; rendered on demand if the working file for that format does not yet exist).

Security

Runs locally over stdio with no authentication. Spawns a local preview web server on ports 3737-3747 (auto-selects an available port). Optional debug logging via the CLAUDE_MERMAID_LOG_LEVEL env var writes to ~/.config/claude-mermaid/logs/.

Claude Mermaid MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Claude Mermaid MCP Server config there under the "mcpServers" key and restart the client.

Is Claude Mermaid MCP Server safe to use with Windsurf?

Which output formats and themes are supported?

Export to SVG, PNG, or PDF, with themes default, forest, dark, and neutral. The browser always shows SVG for live preview; live reload is available for the svg format only, while PNG/PDF are rendered without live reload.

How do I use it with clients other than Claude Code?

Add a standard mcpServers entry with command 'claude-mermaid' to your client's MCP config. The README documents specific setups for Codex (~/.codex/mcp_settings.json), Cursor (.cursor/mcp.json), Cline, Windsurf, and Gemini CLI.

How does live reload work and which ports does it use?

On first render it opens the diagram at http://localhost:3737/{preview_id}; subsequent edits are detected over a WebSocket and the browser auto-refreshes. The server uses ports 3737-3747 and automatically finds an available one. A status indicator shows green (connected) or red (reconnecting).

View repo Full Claude Mermaid MCP Server page