DrawSQL MCP server

Connect your editor#

Claude Code#

Run this once to make DrawSQL available in every project:

claude mcp add --transport http --scope user drawsql https://drawsql.app/mcp

To limit DrawSQL to the current project, omit --scope user.

Codex#

codex mcp add drawsql --url https://drawsql.app/mcp

Cursor#

Add to .cursor/mcp.json in your project, or ~/.cursor/mcp.json for all projects:

{
  "mcpServers": {
    "drawsql": {
      "url": "https://drawsql.app/mcp"
    }
  }
}

Windsurf#

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "drawsql": {
      "serverUrl": "https://drawsql.app/mcp"
    }
  }
}

VS Code#

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "drawsql": {
      "type": "http",
      "url": "https://drawsql.app/mcp"
    }
  }
}

Once connected, ask your agent for a diagram. "Visualize this schema in DrawSQL" or "Diagram the tables in schema.sql" is enough. The agent will choose the tool when it needs it.

What it does#

Connect without a token to turn a schema into an editable diagram with visualize_schema. Add an API token to read your team's diagrams with list_diagrams, get_schema, and get_diagram_link. See Working with your own diagrams. With write access, your agent can also create private diagrams and propose changes that you can review and apply in DrawSQL. Existing diagrams change only when an editor applies a proposal. See Write access.

visualize_schema needs no account. Pass either SQL DDL or a DrawSQL schema patch. The tool returns a drawsql.app/draw link and a summary: driver, table/column/relationship counts, plus any truncation or type remapping. Most clients paraphrase the summary, so expand the tool call to see it raw.

The link opens a full DrawSQL canvas with the tables arranged and foreign keys connected. Anyone with the link can edit, rearrange, or export the diagram without an account.

Links that are never opened expire after 30 days. Opening a link extends its expiry for one year, and each later view renews that period. Save the diagram to an account to keep a permanent copy.

Use the tool whenever your agent can see a schema, whether it lives in a migration folder, a dump file, or the current conversation.

Working with your own diagrams#

Create a token under Account → API tokens and choose your team. API tokens are available on paid plans. Connect your editor with the token in an Authorization: Bearer header.

For example, in Claude Code, use this command instead of the anonymous setup above. If you already added drawsql, remove that entry with claude mcp remove drawsql --scope user before adding it again:

claude mcp add --transport http --scope user drawsql https://drawsql.app/mcp \
  --header "Authorization: Bearer <your-token>"

Replace <your-token> with the token you created. In Claude Code, run /mcp to check the connection. See Claude Code's MCP setup guide for more options.

Write access#

Select Allow writes when creating your token. A token without write access gets the read tools only; write calls fail with insufficient_scope.

A token belongs to one team. create_diagram creates the diagram in that team. propose_diagram_changes also needs the token's user to be able to edit the target diagram.

Once connected with a write token, try:

Propose a nullable notes column on the orders table in my Orders service diagram.

Your agent returns a review link. Open it to inspect the proposed changes. See Reviewing a proposal for how to apply, decline, or undo them.

Each write tool accepts 10 calls per minute per token. To propose a change, the agent calls the tools in this order:

list_diagrams → get_schema → get_driver_rules → propose_diagram_changes → get_proposal_status

The equivalent REST endpoints are POST /v1/diagrams, POST /v1/diagrams/{uuid}/proposals, and GET /v1/proposals/{uuid}. See the REST API.

Authenticated tools#

Tool	What it returns
list_diagrams	The diagrams visible to your token: names, ids, table counts, URLs. Paginated via an opaque cursor.
get_schema	A diagram's schema in the AI Schema Format (level: simple or detailed), the same text as /v1/diagrams/{uuid}/schema?format=ai.
get_diagram_link	A diagram's canvas and embed URLs.
get_driver_rules	For one driver: its data types (params, cross-driver family, aliases), the schema patch format, the size limits, and the call order. Read it before writing a patch.
get_proposal_status	A proposal's state (pending, applied, declined, or expired), when it was opened, applied, or declined, the reviewer's reason for a decline when they gave one, and when it expires. Takes the uuid propose_diagram_changes returned.
create_diagram	Write access. Creates a diagram in the token's team from ddl or a schema patch and returns its link and counts. A DDL import still running after 15 seconds comes back as importing.
propose_diagram_changes	Write access. Stores a schema patch as a proposal against an existing diagram and returns a review link, the proposal's uuid, and counts.

The REST API also provides access over HTTP.

create_diagram#

Send exactly one of ddl or schema.

Parameter	Type	Required	Description
ddl	string	Yes, unless schema is set	SQL CREATE TABLE and ALTER TABLE statements. Up to 200 KB.
schema	string	Yes, unless ddl is set	A DrawSQL schema patch as a JSON string: tables, relationships, groups, and sticky notes. Up to 500 KB. Positions and sizes (left, top, width, height) are rejected.
name	string	No	The diagram name, up to 255 characters. Defaults to Untitled.
driver	string	No	SQL dialect: mysql, pgsql, or sqlsrv. Defaults to mysql.

The call returns within 15 seconds with the diagram link, its uuid, and counts. A DDL import still running at 15 seconds comes back as importing. Poll get_diagram_link with the uuid every 5 seconds until its status is ready; get_schema fails until then. An import that cannot finish reports failed with an error code.

Every diagram created through the API is private. The team's plan table limit applies: 50 tables per diagram on Starter, unlimited on Pro and Team. The same request sent again within two minutes returns the diagram it already created, so a retry does not make a duplicate.

propose_diagram_changes#

Parameter	Type	Required	Description
diagram	string	Yes	The diagram uuid from list_diagrams.
schema	string	Yes	A DrawSQL schema patch as a JSON string: tables, columns, indexes, relationships, groups, sticky notes, and deletions. Up to 500 KB. Positions and sizes are accepted, so the patch may include layout. get_driver_rules returns the full format.
title	string	Yes	A short title for the proposal, like a pull request title. Up to 100 characters.
message	string	Yes	Why the change is needed. Up to 500 characters. The reviewer reads it before deciding.

The call returns a review link, the proposal uuid, the expiry date, and counts of the tables, columns, and relationships it touches (plus groups, sticky notes, and deletions when there are any). The agent hands the link to the user and passes the uuid to get_proposal_status.

Reviewing a proposal#

propose_diagram_changes returns a review link; the agent hands it to the user. The link opens the diagram in the editor with the proposal shown as a diff against the current diagram: the canvas shows the diagram as it is, new tables appear as green previews, and removals are tinted.

Any team member with access to the diagram can view the proposal. If you have permission to edit the diagram, you can apply or decline it from the toolbar. Before applying, DrawSQL highlights destructive changes to the diagram, such as removing tables or columns, and asks you to confirm.

Applying a proposal updates the DrawSQL diagram; it does not run a database migration. Before applying changes, DrawSQL saves a version of the diagram. To restore that version, click Undo in the confirmation notification. This action is separate from the editor's keyboard undo shortcut.

If the diagram changes while you are reviewing the proposal, DrawSQL stops the changes from being applied and asks you to review the updated comparison.

You can include a reason when declining a proposal. get_proposal_status returns that reason to the agent so it can submit a revised proposal. Declined proposals cannot be reopened.

A proposal expires after 30 days. The diagram's History pane lists every proposal with its status, and an editor can reopen an expired one from there. get_proposal_status reports each of these outcomes to the agent.

visualize_schema reference#

visualize_schema takes exactly one of ddl or schema.

Parameter	Type	Required	Description
ddl	string	Yes, unless schema is set	SQL CREATE TABLE and ALTER TABLE statements. Up to 200 KB.
schema	string	Yes, unless ddl is set	A DrawSQL schema patch as a JSON string. Supports tables, columns, indexes, relationships, groups, and sticky notes. See the format in llms-full.txt. Up to 500 KB.
driver	string	No	SQL dialect: mysql, pgsql, or sqlsrv. Defaults to mysql.

An invalid patch returns every problem in one response, each naming the field and the valid values, so the client can fix the whole patch in a single retry. The tool is limited to 10 calls per minute per IP address. The x-ratelimit-* response headers track a separate, looser limit on the HTTP transport (all requests, including handshakes); the tool limit is enforced inside the tool and reported in its error message.

Every call creates a new diagram, so patch fields that describe changes to an existing one are rejected: omit deletions, and omit schema_version unless you have a reason to pin it.

Identifiers are matched exactly, and the tool rejects a patch rather than repairing it: no leading or trailing whitespace and no control characters in names, uuids, or references; table and group names unique; uuids non-empty and unique across the whole patch; and entries that repeat a uuid (to split a large table across entries) must repeat its name. The error names the exact field, so a retry is one edit away.

FAQ#

Do I need a DrawSQL account or an API key?#

Not to turn a schema into a diagram. visualize_schema is anonymous, and returned links open the full editor without signup. Save the diagram to an account if you want a permanent copy or need to share it with your team. The tools that work with your own diagrams need an API token.

What happens to a schema sent to visualize_schema?#

DrawSQL stores the submitted DDL or schema patch so the returned link can load it. An unopened link and its data expire after 30 days. Opening the link extends that period for one year, and each later view renews it.

A success response includes only the driver and parsed counts, never your table or column names. Validation errors quote the specific invalid value they reject, so the client can fix it.

What are the limits for visualize_schema?#

DDL input is limited to 200 KB and schema patches to 500 KB. Either input may describe more than 20 tables; the returned diagram opens with the first 20, and the response says so.

The tool accepts 10 calls per minute per IP address. The HTTP transport allows 20 requests per minute, which also covers handshake and discovery calls; the x-ratelimit-* headers describe that transport limit, not the tool limit.

Which databases are supported?#

MySQL, PostgreSQL, and SQL Server. Pass driver to choose one. The default is MySQL.

Which editors and agents work with it?#

Any MCP client that supports streamable HTTP can connect. The examples above cover Claude Code, Codex, Cursor, Windsurf, and VS Code. There is no local binary to install.

Can my agent read my existing DrawSQL diagrams?#

Yes. Follow the authenticated setup to connect with an API token.

Can my agent change an existing diagram without approval?#

No. An editor must review and apply the proposal in DrawSQL. Creating a new private diagram does not require this review.

What does the agent get back after a proposal?#

A review link and a proposal uuid. The agent uses get_proposal_status to check the outcome. See the tool reference for response details.