MCP Server
turbine mcp starts a read-only Model Context Protocol server, so an AI agent (Claude Code, Cursor or any MCP client) can inspect your database. It speaks JSON-RPC 2.0 over stdio and needs no extra dependency.
DATABASE_URL=postgres://user:pass@localhost:5432/mydb npx turbine mcpConnect a client#
Add the server to your project's .mcp.json for Claude Code, or .cursor/mcp.json for Cursor:
{
"mcpServers": {
"turbine": {
"command": "npx",
"args": ["turbine", "mcp"],
"env": { "DATABASE_URL": "postgres://user:pass@localhost:5432/mydb" }
}
}
}The tools#
| Tool | What it returns |
|---|---|
schema_overview | Tables, columns, relations, indexes and estimated row counts. |
table_detail | Columns, indexes and relations for one table. |
relation_graph | Every relation with its cardinality, target, join keys and junction table. These are the exact names with accepts. |
find_join_path | The shortest relation chains between two tables, with the nested with clause to write. Returns found: false when there is none. |
table_stats | The planner's row estimate, page count, size on disk, and every index. A never-analyzed table reports analyzed: false. |
compile_query | The exact SQL a read query would send, without running it: parameters, statement count, relation strategy, whether a LIMIT bounds it, and warnings such as an unindexed relation. A query that fails to compile returns ok: false with the error code and fix. |
explain_query | EXPLAIN (FORMAT JSON) for a schema-validated findMany. |
sample_rows | Up to 50 rows from one table, with hidden columns never fetched. |
migrate_status | Applied and pending migrations. |
doctor_report | Missing relation indexes, from the same advisor as turbine doctor. |
explain_error | A Turbine error code (TURBINE_E003, E003 or 3) with its class, causes, fix and docs link. Needs no database. |
engine_capabilities | The engine, runtime and transport facts for these tools. Opens no database. |
Those are the twelve tools on PostgreSQL. With --engine sqlite or --engine mysql the server lists nine (no migrate_status, explain_query or table_stats), and with --engine mssql eight (also no sample_rows): SQL Server tools read the catalog and compile queries, and run no data query. SQLite tools open the file read-only and need Node 22.12+.
compile_query takes a table, an operation (findMany, findUnique, findFirst, count, aggregate or groupBy) and the args you would pass that method. explain_query takes table plus optional where, orderBy, limit and select.
Security model#
- On PostgreSQL, every database access runs in
BEGIN READ ONLYwith a 30-second statement timeout. - No tool accepts SQL. Query tools take method arguments, and every name is checked against the live schema.
sample_rowsnever fetches a PII-tagged or secret-named column (password,token,api_keyand similar, in any case style), and lists what it hid.explain_queryandcompile_queryrefuse awhereororderByon such a column, since a row estimate can reveal a value. They also refuse alockoption.- Column names are returned everywhere: a name describes the schema, not the data.
- PII tags come from the generated metadata in
--out. Without it, only the secret-name list applies, and eachsample_rowsreply says so inpiiTagSource. A tag file that cannot be parsed hides every column.
Options#
| Option | Description |
|---|---|
--url, -u <url> | Connection string. Overrides DATABASE_URL. |
--schema, -s <name> | Postgres schema (default public). |
--include <tables> / --exclude <tables> | Comma-separated tables to expose or hide. |
--out, -o <dir> | Generated client directory, where the PII tags are read (default ./generated/turbine). |
See also#
- Turbine for AI agents: the query skill,
llms.txtand a drop-in instructions snippet. - Studio: the same read-only approach, as a web UI.
- CLI:
turbine doctorandmigrate statuson the command line.