drawDB + MCP Server

This fork of DrawDB extends the original with AI assistant integration via Model Context Protocol (MCP). AI assistants like Claude can now create, modify, and manage database diagrams programmatically through a WebSocket API.

Relationship to Upstream DrawDB

This project began as a fork of DrawDB but has since diverged substantially and is intentionally not kept in sync with upstream. Selected fixes and features are occasionally cherry-picked from the parent project, but the two will continue to drift apart as drawdb-mcp evolves on its own. DrawDB remains a separate, actively maintained project, and full credit goes to its authors — see drawdb-io/drawdb.

Demo Video

Watch how to design database schemas using natural language with Claude AI.

Architecture:

• apps/gui: React-based frontend derived from DrawDB
• apps/backend: NestJS MCP server that enables AI assistants to control the diagram editor
• Built with Turborepo and pnpm workspaces

Features

Export & Import

The MCP server provides tools for exporting and importing database diagrams in multiple formats:

Export Formats:

• SQL DDL: Export database-specific SQL statements (PostgreSQL, MySQL, SQLite, MariaDB, MSSQL, Oracle)
• DBML: Export to Database Markup Language (human-readable, database-agnostic format)
• JSON: Export complete diagram state for backup/restore

Import Formats:

• DBML: Import database schemas from DBML format
• JSON: Import complete diagram state

Available MCP Tools:

• export_sql - Export diagram as SQL DDL for current database type
• export_dbml - Export diagram as DBML
• import_dbml - Import database schema from DBML
• export_diagram - Export complete diagram as JSON
• import_diagram - Import complete diagram from JSON

See CLAUDE.md for complete list of available MCP tools and their usage.

Getting Started

Quick Start with Docker (Recommended)

The easiest way to get started is using Docker:

docker run \
  --name drawdb-mcp \
  -p 8080:80 \
  -p 3000:3000 \
  --restart unless-stopped \
  ghcr.io/anatoly-lab/drawdb-mcp:latest

Then:

1. Open GUI: http://localhost:8080
2. Connect Claude Code to the MCP server:

claude mcp add --transport http drawdb-mcp http://127.0.0.1:3000

Now Claude can create and modify database diagrams for you!

See GHCR_DEPLOYMENT.md for available tags and advanced usage.

Local Development

Prerequisites

• Node.js 20.19+ or 22.22+ (see engines in package.json)
• pnpm 8.15.0+ (install via npm install -g pnpm)

Start both GUI and backend:

git clone https://github.com/anatoly-lab/drawdb-mcp
cd drawdb-mcp
pnpm install
pnpm dev

Start GUI only:

pnpm gui:dev
# Access at http://localhost:5173

Start backend only:

pnpm backend:dev
# WebSocket at ws://localhost:3000/remote-control

Build

Build both applications:

pnpm install
pnpm build

Build specific app:

pnpm build --filter=gui
pnpm build --filter=backend

Connect Claude Code to MCP Server

When running locally, connect Claude Code:

claude mcp add --transport http drawdb-mcp http://127.0.0.1:3000

The frontend automatically connects to the backend via WebSocket for real-time updates.

Docker Deployment

See DOCKER_BUILD.md for detailed build instructions.

Build with Docker Compose:

docker-compose up --build
# Access at http://localhost:8080

Or build directly:

docker build -t drawdb-mcp:local .
docker run -p 8080:80 -p 3000:3000 drawdb-mcp:local

The Docker image includes both frontend and backend. WebSocket is proxied through Nginx.

Updating to New Versions

When updating to a new version (whether via Docker or local development), you must perform a hard refresh in your browser to clear the cached frontend JavaScript:

• Windows/Linux: Ctrl + Shift + R or Ctrl + F5
• macOS: Cmd + Shift + R

Without a hard refresh, the browser may continue using the old cached frontend code even though the backend has been updated, which can cause errors or unexpected behavior.

License & Credits

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0), inherited and retained from upstream DrawDB. See the LICENSE file for the full text.

Built on top of DrawDB by the DrawDB authors and contributors. Huge thanks to the original project for the foundation this fork is built on.