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:
-
Environment variable:
export ERASER_API_TOKEN=your_token_here python render_eraser_diagram.py --diagram-type sequence-diagram --code "A -> B"
-
.envfile 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
\nfor 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-diagramcloud-architecture-diagramflowchart-diagramentity-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 .
HTTP Transport (Streamable HTTP)
The server supports both stdio (default) and Streamable HTTP transport for remote access.
Running with HTTP Transport
# Local HTTP server
python main.py --transport http --port 8000
# Server will be available at http://localhost:8000/mcp
Environment Variables
| Variable | Default | Description |
|---|---|---|
ERASER_API_TOKEN |
(required) | Your Eraser.io API token |
MCP_TRANSPORT |
stdio |
Transport protocol: stdio or http |
MCP_HOST |
0.0.0.0 |
Host to bind for HTTP transport |
MCP_PORT |
8000 |
Port to bind for HTTP transport |
MCP_AUTH_TOKEN |
(empty) | Bearer token for HTTP authentication (optional) |
Bearer Token Authentication
To enable authentication for the HTTP endpoint, set MCP_AUTH_TOKEN:
export MCP_AUTH_TOKEN=your_secret_token
python main.py --transport http
Clients must include the token in the Authorization header:
Authorization: Bearer your_secret_token
Docker Deployment
Using Docker Compose (Recommended)
-
Copy
.env.exampleto.envand configure:cp .env.example .env # Edit .env with your ERASER_API_TOKEN
-
Start the server:
docker-compose up -d
-
The server will be available at
http://localhost:8000/mcp
Using Docker Directly
# Build
docker build -t eraser-mcp .
# Run
docker run -p 8000:8000 \
-e ERASER_API_TOKEN=your_token \
-e MCP_AUTH_TOKEN=optional_auth_token \
eraser-mcp
Client Configuration for HTTP
Configure your MCP client to connect via Streamable HTTP:
{
"mcpServers": {
"eraser": {
"type": "streamable-http",
"url": "http://localhost:8000/mcp",
"headers": {
"Authorization": "Bearer your_auth_token"
}
}
}
}
Troubleshooting
- If you get an API error, check that your token in
.envis valid - Use
DEBUG=1to 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 - For HTTP transport issues, check that the port is not in use and firewall allows connections
Metadata
Release files for iflow-mcp_buck-0x-eraser-io-mcp-server 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_buck_0x_eraser_io_mcp_server-1.0.0.tar.gz | 8.7 kB | Without provenance | Details for iflow_mcp_buck_0x_eraser_io_mcp_server-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_buck_0x_eraser_io_mcp_server-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_buck_0x_eraser_io_mcp_server-1.0.0-py3-none-any.whl |
Total release size: 19.1 kB
Release files / iflow_mcp_buck_0x_eraser_io_mcp_server-1.0.0.tar.gz
| Download URL | iflow_mcp_buck_0x_eraser_io_mcp_server-1.0.0.tar.gz |
|---|---|
| Size | 8.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c28b977045d4d090cdf7db406cfe3b53fe5831635c1cf8c2270af6accf98bfc4
|
|
BLAKE2b-256 checksum How to use checksums |
39f94275057ea9fe2c7c178d1bba6597ea93a4dac23c6e91e4f23fb4057e19bb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_buck_0x_eraser_io_mcp_server-1.0.0-py3-none-any.whl
| Download URL | iflow_mcp_buck_0x_eraser_io_mcp_server-1.0.0-py3-none-any.whl |
|---|---|
| Size | 10.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5a877a0a035f1e8996230f70091be0b512fb25ae7fd50e58fe16e30edbd25116
|
|
BLAKE2b-256 checksum How to use checksums |
e2b76e960604c6b4774bb42d7fdf36ddca897747ae2d9da31d40c7b5ca819f7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_buck-0x-eraser-io-mcp-server 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.