dbtrail
Claude Integration

Claude Setup

Connect Claude to dbtrail in 5 minutes. The console serves MCP directly, with no config files

dbtrail exposes your change history to Claude (and any MCP-capable client) through six read-only tools: search changes, draft reversal SQL, draft reversal SQL for foreign-key cascade side effects, reconstruct a row's state at a point in time, show index status, list schema changes. The AI sees exactly what the web console shows you, with the same result caps and the same redactions. It never executes SQL and never connects to your source database: recovery SQL is text you review and run yourself. (Time travel needs a backup configured for that server, exactly like the row-state section of the console's Restore view; without one the tool says so.)

The web console serves MCP directly at /mcp: no separate server to run. Everything on this page starts from one place: open the console → Settings → Connect AI. That page shows your MCP URL, checks that a token is configured, offers the Claude Desktop bundle for download, and has copy-paste snippets for every other client.

The Connect AI page: the console's MCP URL, the access token card, and per-client setup cards for Claude Desktop, claude.ai and Claude Code.

Step 0: generate a token

MCP clients authenticate with an access token: the username/password you use in the browser does not work for them. Since v0.40.0 you mint one without leaving the UI:

Open Settings → Connect AI. If no token is configured, the Access token card has a Generate token button. Click it and copy the value it shows. It appears exactly once and is never stored (only its hash is); the same card rotates or revokes it later, no restart needed. The generated token grants the read-only MCP tools only; it cannot administer the console.

That's the whole step. The token is worth protecting: anyone holding it can read your change history, row images included. Treat it like a database credential.

Step 1: copy your MCP URL

Settings → Connect AI shows it, e.g. http://your-host:8090/mcp.

  • Multiple servers? /mcp targets the console's default server; /mcp/{name} targets a specific one. The card shows the URL for whichever server you have selected in the sidebar.
  • The URL only needs to be reachable from the machine where the AI client runs: LAN, VPN, or an SSH port-forward are all fine. Nothing needs to be on the public internet.

Step 2: connect your client

  1. Download the .mcpb bundle from the Connect AI page (or the releases page). Pick the one matching the machine where Claude Desktop runs.
  2. Double-click it. Claude Desktop opens an install dialog.
  3. Fill in the two fields: the MCP URL from step 1 and your access token (stored by Claude Desktop as a sensitive value).

No config files, no DSNs: the console owns the database connection. Works over private networks: under the hood the bundle runs a local stdio↔HTTP bridge to your console.

Published bundles currently cover Linux; on macOS or Windows use the raw-config fallback shown on the Connect AI page (same two values, five lines of JSON), or build a native bundle from source with make mcpb.

If your console is reachable over public HTTPS, the same /mcp URL works directly: claude.ai → Settings → Connectors → Add custom connector. No bundle, no local install.

Console not public? Use Claude Desktop with the bundle instead; it works over LAN/VPN/tunnels.

Any client that launches stdio MCP servers can use the bridge. The Connect AI page has this snippet ready to copy (.mcp.json for Claude Code, .cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "dbtrail": {
      "command": "bintrail-mcp",
      "args": ["--connect", "http://your-host:8090/mcp", "--token", "YOUR_CONSOLE_TOKEN"]
    }
  }
}

The bintrail-mcp binary ships in the release archives, packages, and Docker image. If the endpoint is unreachable or the token is rejected, the bridge exits with a one-line error instead of hanging silently.

Step 3: ask something

Open a new conversation. The query, recover, recover_cascade, reconstruct, status, and list_schema_changes tools are now available. Try:

"What's the status of my binlog index?"

"Someone fat-fingered an UPDATE on users around 3pm. What did it change, and write me the SQL to undo it."

If the connection is working, Claude calls the tools and answers from the index; it never touches the source database. From there, head to Using Claude with dbtrail for example conversations, or the Tools Reference.

When something doesn't work

The most common failures: 401 (wrong token, or a port-forward pointing at a stale process), 403 "no token configured" (add --token / BINTRAIL_CONSOLE_TOKEN and restart), and connection refused (the URL isn't reachable from the AI client's machine; check curl http://host:8090/api/healthz from there). The full symptom table is in the repository: Connect an AI assistant → troubleshooting.

Headless setups (no console)

CLI-only deployments can run the standalone bintrail-mcp server against the index DSN directly, over stdio for local clients or --http for remote ones. Every option and knob: MCP server reference.

Console on a Hostname

Put the dbtrail console on console.example.com with TLS — DNS, certificate, and the one header rule that returns 403 until you set it

Using Claude with dbtrail

Query your MySQL change history using natural language

On this page

Step 0: generate a tokenStep 1: copy your MCP URLStep 2: connect your clientStep 3: ask somethingWhen something doesn't workHeadless setups (no console)