
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 ofschemity-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.1only 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
- Install Schemity on macOS, Windows, or Linux.
- Open the diagram you want the agent to see, or let the agent find and open a saved one with
find_diagramsandopen_diagram. - 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_BINto the path of theschemitybinary. - 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
- Documentation: AI Agents via MCP
- Impact analysis: what a migration costs before it runs
- Website: schemity.com
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.
schemity-mcpnpm install schemity-mcp