Turbine

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 mcp

Connect 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#

ToolWhat it returns
schema_overviewTables, columns, relations, indexes and estimated row counts.
table_detailColumns, indexes and relations for one table.
relation_graphEvery relation with its cardinality, target, join keys and junction table. These are the exact names with accepts.
find_join_pathThe shortest relation chains between two tables, with the nested with clause to write. Returns found: false when there is none.
table_statsThe planner's row estimate, page count, size on disk, and every index. A never-analyzed table reports analyzed: false.
compile_queryThe 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_queryEXPLAIN (FORMAT JSON) for a schema-validated findMany.
sample_rowsUp to 50 rows from one table, with hidden columns never fetched.
migrate_statusApplied and pending migrations.
doctor_reportMissing relation indexes, from the same advisor as turbine doctor.
explain_errorA Turbine error code (TURBINE_E003, E003 or 3) with its class, causes, fix and docs link. Needs no database.
engine_capabilitiesThe 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 ONLY with a 30-second statement timeout.
  • No tool accepts SQL. Query tools take method arguments, and every name is checked against the live schema.
  • sample_rows never fetches a PII-tagged or secret-named column (password, token, api_key and similar, in any case style), and lists what it hid.
  • explain_query and compile_query refuse a where or orderBy on such a column, since a row estimate can reveal a value. They also refuse a lock option.
  • 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 each sample_rows reply says so in piiTagSource. A tag file that cannot be parsed hides every column.

Options#

OptionDescription
--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.txt and a drop-in instructions snippet.
  • Studio: the same read-only approach, as a web UI.
  • CLI: turbine doctor and migrate status on the command line.