todiagram-mcp-windows-fix
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@todiagram-mcp-windows-fix generate a flowchart for the checkout process"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
todiagram-mcp-windows-fix
Windows-compatible fork of @todiagram/todiagram-mcp that fixes ERR_UNSUPPORTED_ESM_URL_SCHEME on Node.js v22+ and v25+ on Windows.
Connect ToDiagram to Cursor, Claude, Windsurf, and other AI assistants — now works on Windows!
⚠️ The Problem
The original @todiagram/todiagram-mcp crashes on Windows with:
Fatal error in main(): Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]:
Only URLs with a scheme in: file, data, and node are supported by the default ESM loader.
On Windows, absolute paths must be valid file:// URLs. Received protocol 'c:'Root cause: In dist/mcp-server.js, the lazyLoadUtil() function dynamically imports tool modules using path.join(), which on Windows produces paths like C:\Users\...\tools\file.js. The Node.js ESM loader requires file:// URLs, not bare Windows paths.
Related MCP server: fcp-drawio
✅ The Fix
A one-line change in dist/mcp-server.js:
- import { fileURLToPath } from "url";
+ import { fileURLToPath, pathToFileURL } from "url";
// ... in lazyLoadUtil():
- await import(toolPath);
+ await import(pathToFileURL(toolPath).href);pathToFileURL() converts C:\Users\...\file.js → file:///C:/Users/.../file.js, which the ESM loader accepts on all platforms.
📦 Install
npm install -g todiagram-mcp-windows-fix🔧 MCP Configuration
Claude Code (.mcp.json)
{
"mcpServers": {
"todiagram": {
"type": "stdio",
"command": "todiagram",
"env": {
"TODIAGRAM_API_KEY": "your-api-key-here"
}
}
}
}Or via npx
{
"mcpServers": {
"todiagram": {
"type": "stdio",
"command": "npx",
"args": ["-y", "todiagram-mcp-windows-fix"],
"env": {
"TODIAGRAM_API_KEY": "your-api-key-here"
}
}
}
}API Key Setup
Go to ToDiagram Editor
Click the account icon at top right
Go to API Key section
Create a key with a descriptive name and expiry time
🐛 Upstream Issue
This fix should be applied to the original @todiagram/todiagram-mcp package. The upstream issue is in src/mcp-server.ts:
// Current (broken on Windows):
for (const toolPath of toolsPaths) {
await import(toolPath);
}
// Fix:
import { pathToFileURL } from "url";
for (const toolPath of toolsPaths) {
await import(pathToFileURL(toolPath).href);
}Affected platforms: Windows with Node.js v22+ (any version using ESM loader with strict URL scheme validation)
Affected versions: @todiagram/todiagram-mcp v1.1.0 and likely earlier versions
✅ Platform Compatibility
Platform | Node.js v20 | Node.js v22 | Node.js v25 |
Windows | ✅ | ✅ | ✅ |
macOS | ✅ | ✅ | ✅ |
Linux | ✅ | ✅ | ✅ |
📄 License
FSL-1.1-ALv2 (same as upstream)
Available Tools
5 toolsgenerateCodeDiagramGenerate Code DiagramA
Code-level or detailed component diagrams with key-value rows plus optional icons/images. Use for repositories, services, configs, or data-rich nodes. Note: setting imageUrl on a node hides all rows (label + image only); use iconUrl when you need both an icon and key-value fields. For high-level system visuals with mostly image nodes, use generateSystemDiagram.
Inputs: content (required), name.
generateDataDiagramGenerate data diagramA
Generate diagrams from structured data like JSON, YAML, CSV or XML. Use this tool specifically for visualizing raw data structures, configuration files, or API responses.
Inputs: name (required), format (required), content (required).
generateImageDiagramGenerate Image to DiagramA
Convert an image (screenshot, diagram, whiteboard sketch, architecture drawing, etc.) into a ToDiagram custom format diagram. Analyzes the image to identify components, relationships, and hierarchical structure, then generates an equivalent diagram.
Inputs: imageBase64 (required), imageMimeType (required), name, description.
generateMermaidDiagramGenerate Mermaid FlowchartA
Use only when a user explicitly requests raw Mermaid syntax. Great for quick text-only flowcharts or when they need to edit Mermaid directly. For architecture, repositories, and anything that benefits from images/groups, prefer generateSystemDiagram or generateCodeDiagram. Supports optional Iconify icons (e.g., Node["fa:database Database"]). Only flowcharts are supported.
Inputs: name (required), content (required).
generateSystemDiagramGenerate System DiagramA
High-level system/architecture diagrams with grouped image/icon nodes (logos: or fa7-solid:). Keep fields minimal and favor visual nodes. Use nested parent/group nodes when it helps clarity—too many parents at root can get chaotic. Use this for repositories, platform overviews, services, and environment maps.
Inputs: content (required), name.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct diagram type (code, data, system, image, Mermaid), with descriptions explicitly guiding when to use each and highlighting differences (e.g., generateCodeDiagram vs generateSystemDiagram).
All tools follow a consistent 'generate + [DiagramType]' pattern using CamelCase, e.g., generateCodeDiagram, generateDataDiagram, etc.
5 tools is a well-scoped set for a diagram generation server, covering the main diagram categories without unnecessary duplication or missing core functionality.
The tool set covers the major diagram needs: code-level, data, system architecture, image-to-diagram conversion, and Mermaid syntax, with no obvious gaps for the domain.
Related MCP Connectors
MCP server for AI dialogue using various LLM models via AceDataCloud
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server for Qwen Image 3 AI image generation
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to programmatically create and manage flowcharts, ERDs, and swimlane diagrams. It provides tools for manipulating diagram structures, performing auto-layouts, and exporting to Mermaid or Markdown formats.MIT
- AlicenseBqualityDmaintenanceMCP server that enables LLMs to create and edit draw.io diagrams using high-level intent commands, with automatic layout and styling.46 npm4MIT
- AlicenseAqualityDmaintenanceMCP server for generating diagrams, charts, and visualizations using Gemini image generation on Vertex AI. Supports auto-detection of diagram types, multiple style modes, and iterative refinement.3104 npm1MIT
- AlicenseBqualityCmaintenanceMCP server that enables AI assistants to create, parse, render, and validate Draw.io diagrams programmatically.1473 PyPI2MIT