# @diagram-forge/mcp-server

> DiagramForge MCP Server — AI-powered diagram generation with real-time browser preview for Claude, Cursor, and other MCP clients

Latest version **1.2.2** (published 2026-09-23) · Apache-2.0 license · 0 weekly downloads

## Install

```sh
npm install @diagram-forge/mcp-server
pnpm add @diagram-forge/mcp-server
yarn add @diagram-forge/mcp-server
bun add @diagram-forge/mcp-server
```

Provides the command `diagramforge-mcp`.

## Health

**Score 65/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 1.2.2 |
| Published | 2026-09-23 |
| First published | 2026-05-22 |
| Weekly downloads | 0 |
| License | Apache-2.0 |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 4 |
| Unpacked size | 200.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Venkat Meruva |
| Maintainers | dataamigos |
| Keywords | mcp, drawio, diagram, ai, claude, diagramforge, model-context-protocol, architecture, continuous-diagramming |

## Links

- npm: https://www.npmjs.com/package/@diagram-forge/mcp-server
- Repository: https://github.com/dataamigos/diagramforge-releases
- Issues: https://github.com/dataamigos/diagramforge-releases/issues
- npm.io page: https://npm.io/package/@diagram-forge/mcp-server

## Dependencies (4)

- [zod](https://npm.io/package/zod.md) ^4.0.0
- [open](https://npm.io/package/open.md) ^11.0.0
- [linkedom](https://npm.io/package/linkedom.md) ^0.18.0
- [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^1.0.4

## Alternatives

- [@expo/fingerprint](https://npm.io/package/@expo/fingerprint.md) — 6.2M weekly downloads
- [@azure/monitor-opentelemetry-exporter](https://npm.io/package/@azure/monitor-opentelemetry-exporter.md) — 850.0K weekly downloads
- [@azure/monitor-opentelemetry](https://npm.io/package/@azure/monitor-opentelemetry.md) — 624.0K weekly downloads
- [@posthog/ai](https://npm.io/package/@posthog/ai.md) — 423.3K weekly downloads
- [fakefilter](https://npm.io/package/fakefilter.md) — 63.9K weekly downloads

## Recent versions

- 1.2.2 (latest) — 2026-09-23
- 1.2.1 — 2026-09-23
- 1.1.2 — 2026-05-22

## README

# DiagramForge MCP Server

MCP (Model Context Protocol) server that enables AI agents like Claude Desktop and Cursor to generate and edit draw.io diagrams with **real-time browser preview**.

**Self-contained** - includes an embedded HTTP server, no external dependencies required.

## Quick Start

```json
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["@diagram-forge/mcp-server@latest"]
    }
  }
}
```

## Installation

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["@diagram-forge/mcp-server@latest"]
    }
  }
}
```

### VS Code

Add to your VS Code settings (`.vscode/mcp.json` in workspace or user settings):

```json
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["@diagram-forge/mcp-server@latest"]
    }
  }
}
```

### Cursor

Add to Cursor MCP config (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["@diagram-forge/mcp-server@latest"]
    }
  }
}
```

### Cline (VS Code Extension)

1. Click the **MCP Servers** icon in Cline's top menu bar
2. Select the **Configure** tab
3. Click **Configure MCP Servers** to edit `cline_mcp_settings.json`
4. Add the drawio server:

```json
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["@diagram-forge/mcp-server@latest"]
    }
  }
}
```

### Claude Code CLI

```bash
claude mcp add drawio -- npx @diagram-forge/mcp-server@latest
```

### Other MCP Clients

Use the standard MCP configuration with:
- **Command**: `npx`
- **Args**: `["@diagram-forge/mcp-server@latest"]`

## Usage

1. Restart your MCP client after updating config
2. Ask the AI to create a diagram:
   > "Create a flowchart showing user authentication with login, MFA, and session management"
3. The diagram appears in your browser in real-time!

## Features

- **Real-time Preview**: Diagrams appear and update in your browser as the AI creates them
- **Version History**: Restore previous diagram versions with visual thumbnails - click the clock button (bottom-right) to browse and restore earlier states
- **Natural Language**: Describe diagrams in plain text - flowcharts, architecture diagrams, etc.
- **Edit Support**: Modify existing diagrams with natural language instructions
- **Export**: Save diagrams as `.drawio` files
- **Self-contained**: Embedded server, works offline (except draw.io UI which loads from `embed.diagrams.net` by default, configurable via `DRAWIO_BASE_URL`)

## Available Tools

| Tool | Description |
|------|-------------|
| `start_session` | Opens browser with real-time diagram preview |
| `create_new_diagram` | Create a new diagram from XML (requires `xml` argument) |
| `edit_diagram` | Edit diagram by ID-based operations (update/add/delete cells) |
| `get_diagram` | Get the current diagram XML |
| `export_diagram` | Save diagram to a `.drawio` file |

## How It Works

```
┌─────────────────┐     stdio      ┌─────────────────┐
│  Claude Desktop │ <───────────> │   MCP Server    │
│    (AI Agent)   │               │  (this package) │
└─────────────────┘               └────────┬────────┘
                                          │
                                 ┌────────▼────────┐
                                 │ Embedded HTTP   │
                                 │ Server (:6002)  │
                                 └────────┬────────┘
                                          │
                                 ┌────────▼────────┐
                                 │  User's Browser │
                                 │ (draw.io embed) │
                                 └─────────────────┘
```

1. **MCP Server** receives tool calls from Claude via stdio
2. **Embedded HTTP Server** serves the draw.io UI and handles state
3. **Browser** shows real-time diagram updates via polling

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `6002` | Port for the embedded HTTP server |
| `DRAWIO_BASE_URL` | `https://embed.diagrams.net` | Base URL for the draw.io embed. Set this to use a self-hosted draw.io instance for private deployments. |

### Private Deployment (Self-hosted draw.io)

For security-sensitive environments that require private deployment of draw.io:

```json
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["@diagram-forge/mcp-server@latest"],
      "env": { 
        "DRAWIO_BASE_URL": "https://drawio.your-company.com"
      }
    }
  }
}
```

You can deploy your own draw.io instance using the official Docker image:

```bash
docker run -d -p 8080:8080 jgraph/drawio
```

Then set `DRAWIO_BASE_URL=http://localhost:8080` (or your server's URL).

## Troubleshooting

### Port already in use

If port 6002 is in use, the server will automatically try the next available port (up to 6020).

Or set a custom port:
```json
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["@diagram-forge/mcp-server@latest"],
      "env": { "PORT": "6003" }
    }
  }
}
```

### "No active session"

Call `start_session` first to open the browser window.

### Browser not updating

Check that the browser URL has the `?mcp=` query parameter. The MCP session ID connects the browser to the server.

## License

Apache-2.0

---
_Source: https://npm.io/package/@diagram-forge/mcp-server · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._