Mindpilot MCP is a Mermaid diagram generation and rendering tool for visualizing code, architecture, and other concepts in a local web app, primarily aimed at developers using AI coding agents. Its core purpose is to help developers understand legacy code from different perspectives, inspect complex flows, review redundant structures in AI-generated code, and assist in designing new systems.
Main capabilities:
- Generate architecture, code, and flow diagrams on demand: Through natural language requests, the AI agent calls the MCP server to generate Mermaid diagrams and render them in the browser.
- Support multiple diagram types: such as state machine diagrams, C4 context diagrams, sequence diagrams, and more.
- Local processing: Diagrams are not sent to the cloud; the entire process takes place only between the user, the agent, and the LLM provider used by the agent.
- Export and share: Any diagram can be exported as a vector image.
- Multi-client support: When multiple AI assistants are running at the same time (such as multiple Claude Desktop windows or IDE instances), the first MCP client to use Mindpilot starts a shared web server, and other assistants connect automatically, sharing the same diagram history and web interface; after the last client disconnects, the server automatically shuts down after about one minute.
- Anonymous usage data collection: Anonymous usage data is collected by default and can be disabled via a parameter.
How to use: Requires Node.js v20.0.0 or higher. It can be installed as an MCP server into various coding agents. For example, in Claude Code, run: claude mcp add mindpilot -- npx @mindpilot/mcp@latest In Cursor, go to Settings > Cursor Settings > MCP, click Add new global MCP server, and configure mindpilot in the mcpServers object. VS Code requires enabling MCP according to the official guidance (see https://code.visualstudio.com/docs/copilot/chat/mcp-servers）。 In Windsurf, go to Settings > Windsurf Settings > Manage Plugins, click view raw config, and configure mindpilot in the mcpServers object. In the AI Thread panel, click the three dots ..., select Add Custom Server..., enter npx @mindpilot/mcp@latest in the Command to run MCPserver field, and click Add Server.
Configuration options:
- Port: The server's default port is 4000 and can be changed via the --port command-line switch.
- Data path: Diagrams are saved by default to ~/.mindpilot/data/, and a custom location can be specified via --data-path.
- Disable analytics: Add the --disable-analytics flag to the MCP configuration to disable anonymous data collection.
Using the MCP server: After configuration is complete, you can make requests to the coding agent such as "create a diagram about x", and the agent will use the MCP server to render a Mermaid diagram in the browser. Example requests include: "Show me the state machine for WebSocket connection logic", "Create a C4 context diagram of this project's architecture.", "Show me the OAuth flow as a sequence diagram". MCP is designed to accept Mermaid syntax and http://localhost:4000（默认端口）上运行的 Render diagrams in web applications.
Lightweight skill alternative: Mindpilot now also offers a lightweight agent skill that does not require a local MCP server. Installation command: npx skills add abrinsmead/skills/mermaid-viewer. After installation, have the agent generate a diagram, and it will build a self-contained, interactive Mermaid viewer that can be opened in a browser or published as a Claude artifact.
Troubleshooting:
- If port 4000 is occupied by another service, you can configure a different port, for example: claude mcp add mindpilot -- npx @mindpilot/mcp@latest --port 5555
- Example of a custom data path: claude mcp add mindpilot -- npx @mindpilot/mcp@latest --data-path /path/to/custom/location
- When using the asdf version manager, if MCP does not work, you may need to set a "global" nodejs version in the home directory.
Development configuration: Configure MCP in a coding agent, for example using claude: claude mcp add mindpilot -- npx tsx <path to...>/src/server/server.ts To view MCP errors, run claude with the --debug flag. Start the development client (Vite) to get hot module reloading, and open the local development client at localhost:5173.
Use cases: visualizing legacy code, inspecting complex flows, "vibe checking" AI-generated code (finding areas that need cleanup), assisting with system architecture design, and scenarios that require exporting diagrams as vector images for sharing.
