DBTrail
Claude Integration

Claude Setup

Connect Claude to DBTrail in 5 minutes. The web interface serves MCP directly, with no config files

Claude Desktop through the .mcpb bundle's local bridge, claude.ai through a custom connector over public HTTPS, and Claude Code or Cursor through bintrail-mcp --connect all reach the web interface's /mcp endpoint with a token (/mcp/{name} for one server). The web interface reads the change index read-only, with the same caps and redactions as the UI. It never executes SQL and never touches the source database.
Settings, MCP Server, three steps: generate a token, shown once and stored as a hash, rotate or revoke on the same card; copy the MCP URL, /mcp or /mcp/{name}, reachable from the AI client's machine over a LAN, VPN or tunnel; install and ask with the desktop bundle, the claude.ai connector or the bridge for Claude Code and Cursor. Six read-only tools appear.
The MCP Server page: three steps, Create a token with a Generate token button, Copy the address once the token exists, and Add it to Claude with the desktop installer and the two fields to fill in Claude Desktop. Below, Connect a SQL client (off until the port is set at startup), Download a DuckDB schema, and Keep it current with Iceberg.

Step 0: generate a token

Settings → MCP Server → Access token → Generate token. Copy it: it is shown once. It grants the read-only MCP tools only, and anyone holding it can read your change history, row images included. Browser logins do not work for MCP clients.

Token gone after a restart?

The token's hash lives in a file. If the container does not keep that file, clients get a 401 after every restart. Point it at persistent storage: BINTRAIL_CONSOLE_MCP_TOKEN_FILE (CLI: --mcp-token-file on bintrail-console serve, --console-mcp-token-file on watch). The shipped compose file already does.

Step 1: copy your MCP URL

Shown on MCP Server, e.g. http://your-host:8090/mcp. /mcp is the default server; /mcp/{name} targets one server. It only needs to be reachable from the AI client's machine.

Step 2: connect your client

  1. Download the .mcpb bundle for your machine from MCP Server or the releases page.
  2. Double-click it.
  3. Enter the MCP URL and the access token.

Bundles are published for macOS and Linux. Elsewhere: the raw-config snippet on MCP Server, or make mcpb from source.

Web interface on public HTTPS: claude.ai → Settings → Connectors → Add custom connector, same /mcp URL. Not public: use Claude Desktop.

.mcp.json (Claude Code) or .cursor/mcp.json (Cursor); MCP Server has it ready to copy:

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

bintrail-mcp ships in the release archives, packages and Docker image. A bad URL or token exits with a one-line error.

Step 3: ask something

"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."

Examples: Using Claude. Every tool: Tools Reference.

When something doesn't work

SymptomCause
401Wrong token, or a port-forward to a stale process
403 no token configuredNo token on the web interface yet
Connection refusedURL not reachable from the client: curl http://host:8090/api/healthz from there

Full table: troubleshooting. SQL clients use a different door: ProxySQL integration for Flashback.

Headless setups (no web interface)

Standalone bintrail-mcp reads the index DSN directly, over stdio or --http: MCP server reference.

MariaDB

Capture changes from MariaDB, added from the web interface like a MySQL server, nothing installed in your server

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 web interface)