# @drawx/mcp-server

[![npm version](https://img.shields.io/npm/v/@drawx/mcp-server.svg)](https://www.npmjs.com/package/@drawx/mcp-server)
[![CI](https://github.com/SaharshPamecha/drawx-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/SaharshPamecha/drawx-mcp-server/actions/workflows/ci.yml)
[![license: MIT](https://img.shields.io/npm/l/@drawx/mcp-server.svg)](./LICENSE)

**Generate draw.io diagrams and architecture designs from inside Claude, Cursor, or VS Code.**

DrawX MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that gives your AI assistant three tools:

- **`generate_diagram`** — one-shot: natural-language prompt → complete draw.io XML.
- **`architect_design`** — from a brief, produce a High-Level Design diagram (optionally an LLD + design doc).
- **`whoami`** — verify your API key + see remaining quota.

Behind the scenes it calls the DrawX public API, so output matches the DrawX web app exactly.

---

## Requirements

- **Node.js 18+**
- A **DrawX API key** — create one in [DrawX](https://getdrawx.com) → Settings → API keys. Keys start with `drawx_live_`. API access is a paid feature (bundled with the DrawX Pro plan).

## Install

```bash
npm install -g @drawx/mcp-server
```

Or, if your MCP client supports `npx`, no install is needed — reference `npx @drawx/mcp-server` directly.

## Configure your MCP client

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "drawx": {
      "command": "npx",
      "args": ["-y", "@drawx/mcp-server"],
      "env": {
        "DRAWX_API_KEY": "drawx_live_..."
      }
    }
  }
}
```

Restart Claude Desktop. In a new chat, ask *"Draw me a microservices checkout flow"* — Claude will call `generate_diagram` and show the resulting XML.

### Cursor

Edit `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "drawx": {
      "command": "npx",
      "args": ["-y", "@drawx/mcp-server"],
      "env": { "DRAWX_API_KEY": "drawx_live_..." }
    }
  }
}
```

### VS Code (Copilot MCP)

Add to your workspace or user `settings.json`:

```json
{
  "mcp": {
    "servers": {
      "drawx": {
        "command": "npx",
        "args": ["-y", "@drawx/mcp-server"],
        "env": { "DRAWX_API_KEY": "drawx_live_..." }
      }
    }
  }
}
```

---

## Environment variables

| Variable | Required | Purpose |
|---|---|---|
| `DRAWX_API_KEY` | yes | Your DrawX API key (`drawx_live_...`). |
| `DRAWX_API_BASE` | no | Override the API base URL (default `https://getdrawx.com/api/v1`). Useful for staging. |

## Tools reference

### `generate_diagram`
Turn a description into draw.io XML.

**Inputs**
- `prompt` (string, required) — what to draw.
- `mode` — `"flash"` (default), `"pro"`, or `"ultra"`. Trades speed for quality.
- `previousXml` — an existing mxfile to modify.

**Output** — assistant text: a summary line (model, tokens, cost) followed by the full `<mxfile>...</mxfile>` XML in a fenced code block. Paste the XML into [diagrams.net](https://app.diagrams.net) or save as `.drawio`.

### `architect_design`
Run the DrawX Architect Co-Pilot on a brief. Streams intermediate progress; returns a JSON payload with `hld` (and optional `lld`, `doc`).

**Inputs**
- `brief` (string, required, ≥ 20 chars) — what to design.
- `depth` — `"hld"`, `"hld_lld"` (default), or `"hld_lld_doc"`.
- `style` — `"cloud_agnostic"` (default), `"aws"`, `"azure"`, or `"gcp"`.
- `mode` — `"flash"` (default), `"pro"`, or `"ultra"`.

### `whoami`
No inputs. Returns your email, plan, API tier, and remaining monthly API quota.

## Quota + rate limits

API usage is metered on a **separate** tier from your in-app usage. Pro subscribers get 200 API calls / month. The rate limit is 60 requests / minute. On the free plan, API access is not enabled — upgrade at [getdrawx.com](https://getdrawx.com).

## Local development

```bash
git clone https://github.com/SaharshPamecha/drawx-mcp-server
cd drawx-mcp-server
npm install
npm run build
DRAWX_API_KEY=drawx_live_... node dist/index.js  # runs over stdio; use an MCP inspector
npm test
```

## License

MIT © 2026 DrawX