Bintrail MCP Server

Bintrail

Point-in-time recovery for MySQL, without locking tables or changing your schema. Bintrail tails the binary log, keeps every row change with full before/after images in a searchable index, and generates exact reversal SQL when something goes wrong.

SELECT * FROM orders WHERE id = 123 AS OF '2026-05-20 14:00:00' against production MySQL — that's the experience bintrail makes possible.

Requirements

• Go 1.24+ (only when building from source)
• MySQL 8.0+ for the index database
• Source MySQL with binlog_format = ROW and binlog_row_image = FULL — bintrail doctor will tell you exactly what to fix if your source isn't ready

Install

Docker (no Go toolchain required):

docker pull ghcr.io/dbtrail/bintrail:latest
docker run --rm ghcr.io/dbtrail/bintrail:latest --version

Multi-arch (linux/amd64 + linux/arm64), signed with cosign. The image bundles both bintrail and bintrail-mcp. See docs/docker.md for signature verification and docker run usage.

Linux packages: .deb and .rpm for both architectures are attached to each release.

Go install:

go install github.com/dbtrail/bintrail/cmd/bintrail@latest

Build from source:

git clone https://github.com/dbtrail/bintrail
cd bintrail
go build ./cmd/bintrail

Quick start (2 commands)

# 1. Verify prerequisites and get copy-pasteable remediation for anything missing
bintrail doctor \
  --source-dsn "user:pass@tcp(source:3306)/" \
  --index-dsn  "user:pass@tcp(127.0.0.1:3306)/binlog_index"

# 2. Initialize and start streaming (idempotent — safe to re-run)
bintrail up \
  --source-dsn "user:pass@tcp(source:3306)/" \
  --index-dsn  "user:pass@tcp(127.0.0.1:3306)/binlog_index"

bintrail up runs preflight + creates index tables + auto-snapshots + starts streaming, all in one. It resumes from the last checkpoint on restart and auto-derives a unique server-id from your source DSN so you don't have to think about replica collisions.

Once it's running, query and recover:

# Search the index
bintrail query \
  --index-dsn "user:pass@tcp(127.0.0.1:3306)/binlog_index" \
  --schema mydb --table orders --pk 12345

# Generate reversal SQL
bintrail recover \
  --index-dsn "user:pass@tcp(127.0.0.1:3306)/binlog_index" \
  --schema mydb --table orders --event-type DELETE \
  --since "2026-02-19 14:00:00" --until "2026-02-19 14:05:00" \
  --output recovery.sql

Managed MySQL (RDS, Aurora, Cloud SQL)? bintrail up connects over the replication protocol — no disk access to binlogs required. See Streaming.

Want manual control of each step? See Step-by-step setup below for the underlying init / snapshot / stream commands.

New to bintrail? See the Practical Guide for DBAs for scenario-based walkthroughs and troubleshooting.

Step-by-step setup

If you prefer running each phase explicitly (e.g. to deploy init and stream on separate hosts), the underlying commands remain available:

# 1. Verify prereqs (same as `bintrail up` Phase 1)
bintrail doctor --source-dsn "$SRC" --index-dsn "$IDX"

# 2. Create index tables
bintrail init --index-dsn "$IDX"

# 3. Snapshot schema metadata
bintrail snapshot --source-dsn "$SRC" --index-dsn "$IDX"

# 4. Either: stream live (recommended)
bintrail stream --source-dsn "$SRC" --index-dsn "$IDX" --server-id 12345

# Or: index from binlog files on disk
bintrail index --binlog-dir /var/lib/mysql --source-dsn "$SRC" --index-dsn "$IDX" --all

Commands

All commands accept --log-level (default info) and --log-format (default text). See each command's --help for flags and usage.

MCP Server

Bintrail ships an MCP server that exposes query, recover, and status as read-only tools — letting Claude (or any MCP client) explore your binlog index conversationally.

Claude Connector

The easiest way to connect — works from claude.ai, Claude Desktop, and Claude mobile:

1. Deploy the MCP Gateway (handles OAuth + tenant routing)
2. In Claude, go to Settings > Integrations > Add custom integration
3. Enter your gateway URL (e.g. https://mcp.dbtrail.com/mcp)
4. Authorize with your tenant ID — done

Claude Code (local)

The project ships .mcp.json which pre-registers the server using go run:

{
  "mcpServers": {
    "bintrail": {
      "command": "go",
      "args": ["run", "./cmd/bintrail-mcp"],
      "env": { "BINTRAIL_INDEX_DSN": "user:pass@tcp(127.0.0.1:3306)/binlog_index" }
    }
  }
}

Set BINTRAIL_INDEX_DSN to your index database DSN, then enable with claude mcp enable bintrail.

See MCP Server docs for HTTP mode, proxy setup, and tool details.

How it works

Source MySQL            Index MySQL
(information_schema) ──snapshot──► schema_snapshots
                                        │
Binlog files on disk ──index──►   binlog_events (partitioned)
                                  index_state
                                        │
Replication stream   ──stream──►  binlog_events (partitioned)
                                  stream_state (checkpoint)
                                        │
                          query / recover ──► stdout / .sql file

The index stores complete before and after row images for every event, so recovery never requires the original binlog files.

bintrail index reads binlog files directly from disk — best for self-managed MySQL where the binlog directory is accessible.

bintrail stream connects as a replica over the replication protocol — best for managed MySQL (RDS, Aurora, Cloud SQL) where binlog files are not directly accessible.

Documentation

Agent exit codes

bintrail agent uses distinct process exit codes so a supervisor (e.g. systemd) can distinguish permanent failures from transient ones:

For systemd, add RestartPreventExitStatus=64 65 to the service unit so the agent is not respawned on permanent failures.

License

This project is licensed under the Business Source License 1.1. You may use bintrail for any purpose, including production use, except offering it as part of a competing commercial hosted service or managed consulting service. Each version converts to Apache License 2.0 four years after its release.

For alternative licensing arrangements, contact daniel@dbtrail.com.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md before opening a pull request. All contributors must agree to the Contributor License Agreement — first-time contributors will be prompted automatically via CLA Assistant.