Skip to main content
Glama
todiagram-mcp-windows-fix

todiagram-mcp-windows-fix

by JehadurRE

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

  1. Go to ToDiagram Editor

  2. Click the account icon at top right

  3. Go to API Key section

  4. 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 tools
generateCodeDiagramGenerate 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

    A4.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    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).

    Naming Consistency5/5

    All tools follow a consistent 'generate + [DiagramType]' pattern using CamelCase, e.g., generateCodeDiagram, generateDataDiagram, etc.

    Tool Count5/5

    5 tools is a well-scoped set for a diagram generation server, covering the main diagram categories without unnecessary duplication or missing core functionality.

    Completeness5/5

    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

    Related MCP Servers