Skip to content
Back to search

mindpilot-mcp

See through your agent's eyes. Visualize legacy code, architect new systems, understand everything.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/abrinsmead--mindpilot-mcp/badge.svg)](/listings/abrinsmead--mindpilot-mcp)

HTML

<a href="/listings/abrinsmead--mindpilot-mcp"><img src="/api/listings/abrinsmead--mindpilot-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Claude Code

`claude mcp add mindpilot -- npx @mindpilot/mcp@latest`

Cursor

Under `Settings` > `Cursor Settings` > `MCP` > Click `Add new global MCP server` and configure mindpilot in the `mcpServers` object.

{
  "mcpServers": {
    "mindpilot": {
      "command": "npx",
      "args": ["@mindpilot/mcp@latest"]
    }
  }
}

VS Code

Follow the instructions here for enabling MCPs in VS Code: https://code.visualstudio.com/docs/copilot/chat/mcp-servers

Go to `Settings` > `Features` > `MCP`, then click `Edit in settings json`

Then add mindpilot to your MCP configuration:

{
  "mcp": {
    "servers": {
      "mindpilot": {
        "type": "stdio",
        "command": "npx",
        "args": ["@mindpilot/mcp@latest"]
      }
    }
  }
}

Windsurf

Under `Settings` > `Windsurf Settings` > `Manage Plugins`, click `view raw config` and configure mindpilot in the `mcpServers` object:

{
  "mcpServers": {
    "mindpilot": {
      "command": "npx",
      "args": ["@mindpilot/mcp@latest"]
    }
  }
}

Zed

In the AI Thread panel click on the three dots `...`, then click `Add Custom Server...`

In the `Command to run MCPserver` field enter `npx @mindpilot/mcp@latest` and click `Add Server`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 177 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

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

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.