Mindpilot MCP

1# Mindpilot MCP
2[![GitHub Repo stars](https://img.shields.io/github/stars/abrinsmead/mindpilot-mcp)](https://github.com/abrinsmead/mindpilot-mcp)
3[![NPM Version](https://img.shields.io/npm/v/@mindpilot/mcp)](https://www.npmjs.com/package/@mindpilot/mcp)
4[![GitHub License](https://img.shields.io/github/license/abrinsmead/mindpilot-mcp)](https://github.com/abrinsmead/mindpilot-mcp/blob/main/LICENSE)
5 
6See through your agent's eyes. Visualize legacy code, inspect complex flows, understand everything.
7 
8![Screenshot](https://raw.githubusercontent.com/abrinsmead/mindpilot-mcp/main/mindpilot-mcp-latest.png)
9 
10## Why Mindpilot?
11- **Visualize Anything**: Use your coding agent to generate on-demand architecture, code, and process diagrams to view your code from different perspectives.
12- **Vibe Checks**: AI-generated code can accumulate unused and redundant constructs. Use visualizations to spot areas that need cleanup.
13- **Local Processing**: Diagrams are never sent to the cloud. Everything stays between you, your agent, and your agent's LLM provider(s).
14- **Export & Share**: Export any diagram as a vector image.
15 
16## Prerequisites
17 
18Node.js v20.0.0 or higher.
19 
20## Quickstart
21 
22### Claude Code
23`claude mcp add mindpilot -- npx @mindpilot/mcp@latest`
24 
25### Cursor
26 
27Under `Settings` > `Cursor Settings` > `MCP` > Click `Add new global MCP server` and configure mindpilot in the `mcpServers` object.
28 
29```
30{
31  "mcpServers": {
32    "mindpilot": {
33      "command": "npx",
34      "args": ["@mindpilot/mcp@latest"]
35    }
36  }
37}
38```
39 
40### VS Code
41Follow the instructions here for enabling MCPs in VS Code:  https://code.visualstudio.com/docs/copilot/chat/mcp-servers
42 
43Go to `Settings` > `Features` > `MCP`, then click `Edit in settings json`
44 
45Then add mindpilot to your MCP configuration:
46 
47```
48{
49  "mcp": {
50    "servers": {
51      "mindpilot": {
52        "type": "stdio",
53        "command": "npx",
54        "args": ["@mindpilot/mcp@latest"]
55      }
56    }
57  }
58}
59```
60 
61### Windsurf
62 
63Under `Settings` > `Windsurf Settings` > `Manage Plugins`, click `view raw config` and configure mindpilot in the `mcpServers` object:
64 
65```
66{
67  "mcpServers": {
68    "mindpilot": {
69      "command": "npx",
70      "args": ["@mindpilot/mcp@latest"]
71    }
72  }
73}
74```
75 
76### Zed
77In the AI Thread panel click on the three dots `...`, then click `Add Custom Server...`
78 
79In the `Command to run MCPserver` field enter `npx @mindpilot/mcp@latest` and click `Add Server`.
80 
81## Configuration Options
82- **Port**: The server defaults to port 4000 but can be configured using the `--port` command line switch.
83- **Data Path**: By default, diagrams are saved to `~/.mindpilot/data/`. You can specify a custom location using the `--data-path` command line switch.
84 
85## Multi-Client Support
86 
87Mindpilot intelligently handles multiple AI assistants running simultaneously. When you have multiple Claude Desktop windows or IDE instances open:
88 
89- The first mcp client to use Mindpilot starts a shared web server
90- Additional assistants automatically connect to the existing server
91- All assistants share the same diagram history and web interface
92- The server will automatically shuts down a minute after the last MCP clinet disconnects
93 
94This means you can work with multiple MCP hosts at once without port conflicts, and they'll all contribute to the same collection of diagrams.
95 
96## Anonymous Usage Tracking
97 
98Mindpilot MCP collects anonymous usage data to help us understand how the product is being used and improve the user experience.
99 
100### Disabling Analytics
101If you prefer not to share anonymous usage data, you can disable analytics by adding the `--disable-analytics` flag to your MCP configuration:
102 
103**Claude Code:**
104```bash
105claude mcp add mindpilot -- npx @mindpilot/mcp@latest --disable-analytics
106```
107 
108**Other IDEs:**
109Add `"--disable-analytics"` to the args array in your configuration:
110```json
111{
112  "command": "npx",
113  "args": ["@mindpilot/mcp@latest", "--disable-analytics"]
114}
115```
116 
117## Using the MCP server
118After configuring the MCP in your coding agent you can make requests like "create a diagram about x" and it should use the MCP server to render Mermaid diagrams for you in a browser connected to the MCP server.
119 
120You can optionally update your agent's rules file to give specific instructions about when to use mindpilot-mcp.
121 
122### Example requests
123- "Show me the state machine for WebSocket connection logic"
124- "Create a C4 context diagram of this project's architecture."
125- "Show me the OAuth flow as a sequence diagram"
126 
127## How it works
128Frontier LLMs are well trained to generate valid Mermaid syntax. The MCP is designed to accept Mermaid syntax and render diagrams in a web app running on http://localhost:4000 (default port).
129 
130## Troubleshooting
131 
132### Port Conflicts
133If you use port 4000 for another service you can configure the MCP to use a different port.
134 
135Claude Code example:
136`claude mcp add mindpilot -- npx @mindpilot/mcp@latest --port 5555`
137 
138### Custom Data Path
139To save diagrams to a custom location (e.g., for syncing with cloud storage):
140 
141Claude Code example:
142`claude mcp add mindpilot -- npx @mindpilot/mcp@latest --data-path /path/to/custom/location`
143 
144Other IDEs:
145```json
146{
147  "command": "npx",
148  "args": ["@mindpilot/mcp@latest", "--data-path", "/path/to/custom/location"]
149}
150```
151 
152### asdf Issues
153If you use `asdf` as a version manager and have trouble getting MCPs to work (not just mindpilot), you may need to set a "global" nodejs version from your home directory.
154 
155```
156cd
157asdf set nodejs x.x.x
158```
159 
160## Development Configuration
161Configure the MCP in your coding agent (using `claude` in this example)
162 
163`claude mcp add mindpilot -- npx tsx <path to...>/src/server/server.ts`
164 
165Run `claude` with the `--debug` flag if you need to see MCP errors
166 
167Start the development client (Vite) to get hot module reloading while developing.
168 
169`npm run dev`
170 
171Open the development client
172`localhost:5173`
173