Repository avatar
Databases
v1.0.0
active

mcp

com.schemity/mcp

Local database MCP server: the agent reads your schema and stages edits, never holding credentials.

Documentation

Schemity MCP Server

A local database MCP server built into Schemity, database design software for software engineers. Your AI agent reads the schema of your live PostgreSQL, CockroachDB, MySQL, MariaDB, SQL Server, SQLite, Cloudflare D1, or Snowflake database, sees what a migration would do before it runs, and stages diagram edits you review. The agent never gets database credentials, and nothing it does writes to a database.

The server ships inside the Schemity desktop app, which is closed source. This repository holds its documentation, the tool list it exposes (tools.json), ready-to-paste host configs (examples/), and the source of schemity-mcp, a small npm launcher that finds the installed app and starts its server. Bug reports and feature requests go to schemity-feedback.

Why a governed path

Most database MCP servers hand the agent a connection string and run whatever SQL it writes. Schemity works the other way round: the agent works through the diagram you have open, which Schemity read from your database.

  • Reads never change anything.
  • Edits are staged in the open diagram as unsaved changes, recorded in undo history under the agent's name, for you to review and undo before you save.
  • Nothing touches a database until you run the migration yourself.
  • No vendor cloud in the middle. The HTTP server listens on 127.0.0.1 only and requires a bearer token kept in your OS keychain; stdio hosts talk to the app over a local socket. Your schema goes only where your agent host already sends your code, and with a local model it stays on your machine.

Tools

19 tools and 3 prompts, as of Schemity 2.14.9. None of them runs SQL the agent writes, and none returns a row. Full input schemas are in tools.json.

list_diagrams

The diagrams open in Schemity right now, with the active tab marked. Read-only.

find_diagrams

Every saved diagram, open or not, matched by name, database, or workspace, best match first. Read-only.

open_diagram

Open a saved diagram in a new tab, or bring it to the front. Opening one with a database may ask for your OS keychain password.

open_schemity

Start Schemity, or bring it to the front.

get_schema

Tables, columns, keys, checks, and indexes of a diagram or one context view, plus your naming convention and the template new tables start with. No row data. Read-only.

get_dependencies

Relations into and out of one table, with the columns on both sides. Read-only.

get_context_views

Context views, the dependencies between them, cycles, and which dependencies are not declared as foreign keys. Read-only.

get_data_dictionary

The documented schema as Markdown, descriptions included. Read-only.

lint

Schema findings: conventions, missing indexes, type mismatches. Read-only.

get_pending_changes

The diagram's unsaved edits, as the undo history that produced them. Read-only.

analyze_impact

What the pending migration would cost: lost data, statements that fail on existing rows, table rewrites, locks on large tables, dependent views and functions. SQL only on request, never run. Read-only.

analyze_migration_file

The same analysis for a migration file, hand-written or generated by Prisma, Alembic, or Flyway. Parsed, never run. Read-only.

count_rows

An exact count behind a finding, as a SELECT COUNT with a 60-second timeout, only when you ask for it.

show_preview

Draw pending edits, a migration file, or a set of tables in Schemity for you to look at, with the findings; nothing is saved.

propose_changes

Create, change, and delete tables, columns, relations, constraints, indexes, legends, and context views. Staged as unsaved edits you review; deleting anything you made asks you first.

group_entities

Group tables into legends by domain, from your source code or your description. Staged as unsaved edits you review.

arrange_entities

Place a few tables in rows and columns, the way round you ask for. Staged as unsaved edits you review.

route_relations

Route relation lines around the tables so they cross less. Staged as unsaved edits you review.

check_relation_lines

Relation lines that overlap or cross, and how many bends they take. Read-only.

Prompts

Three step-by-step requests that call the right tools in the right order. Claude Code lists them as /mcp__schemity__<name> slash commands; other hosts show them wherever they list a server's prompts.

  • organize_by_domain - group a diagram's tables into domains learned from the codebase, route the lines, make a context view per domain, and report the dependencies and cycles between domains.
  • review_migration - check a migration against the live database of a connected diagram: data loss, statements that can fail on existing rows, rewrites, dependent views, triggers and functions. Nothing is run.
  • design_feature - design the tables, columns, relations and constraints a feature needs as unsaved changes on a diagram, lint them, and show what the migration would cost. Nothing is saved or run.

Example prompts

Ask in plain words. Your agent host gives the model every tool with its description, and the model calls Schemity's when the request fits one. Saying "in Schemity", "the diagram" or a diagram's name makes that clear; in a code repository, "add a status column" alone may send the agent to your model files instead.

  • "Which diagrams do I have open in Schemity?"
  • "Open my Coffee Shop diagram."
  • "Explain the schema in the current diagram. What are the main domains?"
  • "What depends on the orders table?"
  • "Arrange the current diagram: group the tables by domain, using this codebase to decide the groups."
  • "Untangle the relation lines in the Billing diagram."
  • "Show me the changes in the Coffee Shop diagram."
  • "What would my unsaved changes cost if I migrate?"
  • "Check migrations/0042_add_status.sql against the shop database before I run it."
  • "Add a loyalty_points table to the diagram, linked to customers."

Databases

PostgreSQL, Supabase, CockroachDB, MySQL, MariaDB, SQL Server, and SQLite, directly or through an SSH tunnel, plus Cloudflare D1 and Snowflake.

Setup

  1. Install Schemity on macOS, Windows, or Linux.
  2. Open the diagram you want the agent to see, or let the agent find and open a saved one with find_diagrams and open_diagram.
  3. Open the MCP panel from the plug icon in the control bar, or with Cmd+Shift+A (macOS) / Ctrl+Shift+A (Windows, Linux). It lists Claude Code, Claude Desktop, Cursor, Codex and OpenCode with an Add button each. Add writes the entry into that app's own settings file; restart the app afterwards. No port and no token are needed.

To set a host up by hand instead, use one of the two forms below.

With npx: any stdio host

schemity-mcp finds the installed app on macOS, Windows, or Linux and starts its server, so the same entry works on every platform:

{
  "mcpServers": {
    "schemity": {
      "command": "npx",
      "args": ["-y", "schemity-mcp"]
    }
  }
}

Claude Code

claude mcp add --scope user schemity -- npx -y schemity-mcp

If Schemity is installed somewhere else (an AppImage, a custom folder), set the SCHEMITY_BIN environment variable to the path of the schemity binary.

With the binary path: Claude Code, Claude Desktop, Cursor, Codex, OpenCode

The host starts the Schemity binary with --mcp, so it can also launch Schemity when the app is closed. This is what the Add button writes. The examples use the macOS path; on Windows and Linux, copy the snippet from the MCP panel.

Claude Code

claude mcp add --scope user schemity -- "/Applications/Schemity.app/Contents/MacOS/schemity" --mcp

Claude Desktop (claude_desktop_config.json) and Cursor (~/.cursor/mcp.json), then restart the app

{
  "mcpServers": {
    "schemity": {
      "command": "/Applications/Schemity.app/Contents/MacOS/schemity",
      "args": ["--mcp"]
    }
  }
}

Codex - ~/.codex/config.toml

[mcp_servers.schemity]
command = "/Applications/Schemity.app/Contents/MacOS/schemity"
args = ["--mcp"]

OpenCode - opencode.json

{
  "mcp": {
    "schemity": {
      "type": "local",
      "command": ["/Applications/Schemity.app/Contents/MacOS/schemity", "--mcp"]
    }
  }
}

Streamable HTTP: any other client

Keep Schemity open; an HTTP host cannot start it. The port defaults to 7332 and can be changed in the panel.

{
  "mcpServers": {
    "schemity": {
      "url": "http://127.0.0.1:7332/mcp",
      "headers": { "Authorization": "Bearer <token from the MCP panel>" }
    }
  }
}

Troubleshooting

  • "Schemity is not running" - only a stdio host can start the app. On an HTTP host, open Schemity yourself and retry.
  • 401 Unauthorized - the token was regenerated in the panel; copy the current one into the host's config.
  • Port in use - pick another port in the panel and click Restart.
  • "Schemity is not installed where schemity-mcp looks for it" - install the desktop app, or set SCHEMITY_BIN to the path of the schemity binary.
  • A tool says a feature is not available on the expired trial - the server itself stays free, and the agent can do what you can still do in the app: read the schema and edit tables, relations and legends. Lint, impact analysis, the change preview, row counts, the data dictionary and context views need a license, for an agent as for a person.
  • A tool says a diagram is "not open" - ask the agent to open it with open_diagram, or open it in the Schemity window yourself.

Requirements and pricing

The MCP server is a desktop feature. During the 2-week free trial (no credit card) and with a license, a one-time purchase of $129, every tool works. After the trial the server keeps running for free with the tools that match what the app still lets you do by hand: reading the schema and editing tables, relations and legends. It is not part of Schemity Lite, the free browser version.

Links

License

The launcher, the documentation and the example configs in this repository are MIT licensed (LICENSE). The Schemity desktop app, which contains the MCP server, is closed source.

NPM
schemity-mcp
Install Command
npm install schemity-mcp