What is Eraser Io Mcp Server

eraser-io-mcp-server is a Python-based Model Context Protocol (MCP) server and command-line interface (CLI) tool designed to render various types of diagrams using the Eraser API.

Use cases

Use cases include generating sequence diagrams for software interactions, creating flowcharts for process mapping, designing ER diagrams for database structures, and visualizing cloud architecture.

How to use

To use eraser-io-mcp-server, run the command python render_eraser_diagram.py --diagram-type <type> --code <diagram_code> in your terminal, replacing <type> with the desired diagram type and <diagram_code> with the corresponding Eraser syntax.

Key features

Key features include support for multiple diagram types (sequence, flowchart, ER, cloud architecture), customizable themes and backgrounds, flexible output options (image URLs or base64-encoded content), and icon validation for undefined icons.

Where to use

eraser-io-mcp-server can be used in software development, system architecture design, educational purposes, and any field that requires visual representation of processes or structures.

Eraser Diagram Renderer

A Python MCP (Model Context Protocol) server and CLI tool to render diagrams using the Eraser API.

Features

• 📊 Multiple Diagram Types: Sequence, flowchart, ER, cloud architecture, and more
• 🎨 Customizable: Themes, backgrounds, and scaling options
• 📦 Flexible Output: Get image URLs or base64-encoded file content
• 🔗 Eraser File URL: Returns link to edit diagram in Eraser
• ✅ Icon Validation: Checks for undefined icons and provides warnings

Documentation

• MCP Usage Guide - How to use with Claude Desktop, VS Code, Windsurf, or other environments.
• Eraser Docs - General Eraser documentation
• Eraser Diagram-as-code Documentation - Information about the syntax
• Eraser DSL API Reference - Information about the endpoints and parameters used

Basic Usage

python render_eraser_diagram.py --diagram-type sequence-diagram --code "Alice -> Bob: Hello"

This will output JSON with the image URL:

{
  "success": true,
  "message": "Diagram rendered successfully",
  "image_url": "https://app.eraser.io/workspace/...",
  "create_eraser_file_url": "https://app.eraser.io/workspace/..."
}

If undefined icons are detected:

{
  "success": true,
  "message": "Diagram rendered successfully",
  "image_url": "https://app.eraser.io/workspace/...",
  "create_eraser_file_url": "https://app.eraser.io/workspace/...",
  "warning": "Warning: The following icons are not defined in the standard Eraser icons list: custom-icon. These icons may not render correctly. You can disable this warning by setting SKIP_ICON_CHECK=true."
}

Parameters

• --diagram-type (required): Type of diagram (e.g., sequence-diagram, cloud-architecture-diagram)
• --code (required): Diagram code in Eraser syntax
• --return-file: Return base64-encoded image data instead of URL (defaults to False)
• --no-background: Disable background (defaults to background enabled)
• --theme: Choose “light” or “dark” theme (defaults to “light”)
• --scale: Scale factor - “1”, “2”, or “3” (defaults to “1”)

Note: Due to a bug in the Eraser API, the image cache is only invalidated when the diagram code changes. Changes to theme or background parameters alone will not generate a new image if the same code was previously rendered with different settings.

Authentication

For CLI usage, set your Eraser API token in one of these ways:

1. Environment variable:

   export ERASER_API_TOKEN=your_token_here
   python render_eraser_diagram.py --diagram-type sequence-diagram --code "A -> B"
   

2. .env file in the project directory:

   echo "ERASER_API_TOKEN=your_token_here" > .env
   

For MCP server usage with Claude Desktop, see the MCP Usage Guide.

Icon Validation

This tool validates icon references against the standard Eraser icons list (provided in eraser-standard-icons.csv). If you use custom icons that aren’t in the standard list:

• You’ll receive a warning in the response

• The diagram will still be generated

• To disable icon validation, set SKIP_ICON_CHECK=true:

  SKIP_ICON_CHECK=true python render_eraser_diagram.py --diagram-type flowchart --code "custom-icon: My Service"
  

Handling Special Characters

For multi-line diagrams and special characters:

• Use \n for line breaks
• Use \" for quotes within the code
• Use \\ for literal backslashes

Examples

Multi-line sequence diagram (returns URL):

python render_eraser_diagram.py --diagram-type sequence-diagram \
  --code "Alice -> Bob: Hello\nBob -> Alice: Hi there\nAlice -> Bob: How are you?"

Output:

{
  "success": true,
  "message": "Diagram rendered successfully",
  "image_url": "https://app.eraser.io/workspace/...",
  "create_eraser_file_url": "https://app.eraser.io/workspace/..."
}

With JSON data and return file:

python render_eraser_diagram.py --diagram-type sequence-diagram \
  --code "User -> API: POST /data {\"key\": \"value\"}\nAPI -> User: 200 OK" \
  --return-file

Output:

{
  "success": true,
  "message": "Diagram rendered successfully",
  "image_blob": "iVBORw0KGgoAAAANSUhEUgA..."
}

Cloud architecture with light theme:

python render_eraser_diagram.py --diagram-type cloud-architecture-diagram \
  --code "AWS S3 Bucket\n|\nAWS Lambda" --theme light

Debug mode to see processed code:

DEBUG=1 python render_eraser_diagram.py --diagram-type sequence-diagram \
  --code "A -> B: Test\nB -> C: Response"

Supported Diagram Types

• sequence-diagram
• cloud-architecture-diagram
• flowchart-diagram
• entity-relationship-diagram
• And more (check Eraser Diagram-as-code documentation)

Requirements

• Python 3.10 or higher
• Eraser API token

Installation

Using pip:

pip install -e .

Using uv (fast Python package manager):

uv pip install -e .

Troubleshooting

• If you get an API error, check that your token in .env is valid
• Use DEBUG=1 to see how your code is being processed
• Ensure proper escaping of special characters in your shell
• If you see icon warnings, check if your icons are custom or set SKIP_ICON_CHECK=true