Lets an AI client query MySQL row history, forensic change attribution, and undo SQL through read-only tools.
Also known as dbtrail/bintrail, bintrail
- Stars
- 71
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.0
- Last commit
- Nov 15, 2026
- License
- Apache-2.0
What is DBTrail MCP?
DBTrail lets an AI client query MySQL row history, forensic change attribution, and undo SQL through read-only tools.
Summary generated from the project's README
About DBTrail MCP server
Querying historical MySQL data and performing forensic analysis from inside an AI client is what dbtrail enables. It allows developers to use read-only tools to investigate row history, attribute changes, and generate undo SQL without running heavy analytical queries on the primary database. The server follows the binlog of your MySQL 8.0+, RDS, Aurora, Percona, or MariaDB instance to create a columnar copy in Parquet format using DuckDB.
This setup runs locally or on your own infrastructure via Docker, ensuring your data stays within your environment. It works by routing heavy reads to the columnar copy while keeping transactions and key lookups on the main server. Users connect their AI clients, such as Claude, to interact with the database using plain language. Because the tools are read-only, the AI can investigate what was deleted or how a specific row looked at a previous timestamp without risking the integrity of the live production environment.
What you can do with it
- 1Investigate recent data deletionsAsk the AI client to identify which specific records were removed from a table within a certain timeframe.
- 2Execute heavy analytical queriesRun complex reports and large-scale aggregations that would otherwise slow down the production database.
Written from the project's README. Every use case is checked against a quote from it.
How to install DBTrail MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall DBTrail MCP in Claude Code
$ claude mcp add --transport http bintrail https://api.dbtrail.com/mcpInstall DBTrail MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"bintrail": {
"url": "https://api.dbtrail.com/mcp"
}
}
}Install DBTrail MCP in VS Code
.vscode/mcp.json
{
"servers": {
"bintrail": {
"type": "http",
"url": "https://api.dbtrail.com/mcp"
}
}
}Install DBTrail MCP in VS Code CLI
$ code --add-mcp '{"name":"bintrail","type":"http","url":"https://api.dbtrail.com/mcp"}'Install DBTrail MCP in Codex
$ codex mcp add bintrail --url https://api.dbtrail.com/mcpInstall DBTrail MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.bintrail] url = "https://api.dbtrail.com/mcp"
Install DBTrail MCP in Gemini CLI
$ gemini mcp add -s user --transport http bintrail https://api.dbtrail.com/mcpInstall DBTrail MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"bintrail": {
"url": "https://api.dbtrail.com/mcp",
"type": "http"
}
}
}Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubHTAP for MySQL and MariaDB. Transactions stay on your server; heavy queries come back in seconds from a columnar copy that follows your binlog, routed automatically on the same connection, with no ETL and nothing installed on your MySQL.
Website · Quick Start · Docs · Blog
mysql -h <dbtrail host> -P 3309 -u shop -p
SELECT c.tier, count(*) AS orders, round(sum(o.total), 2) AS revenue
FROM orders o JOIN customers c ON c.id = o.customer_id
GROUP BY c.tier ORDER BY revenue DESC;
What you can do
- Run heavy queries in seconds. Totals and rankings over whole tables, trends over years of data, page 5,000 of a listing. In our test, the heaviest of 14 real reports took 225 seconds on a MySQL replica and 7.9 with DBTrail; the 14 ran 6.5 times faster on average. The numbers
- Keep one connection for your application. With routing on, DBTrail sends writes, transactions and lookups by key to your MySQL, and answers the heavy reads from the copy. Your application's SQL stays as it is. It also works behind ProxySQL. Connect your application
- Point dashboards at it. Metabase, Grafana or any tool that speaks MySQL. Dashboards
- Undo a wrong change. DBTrail keeps every change on your MySQL server, before and after, and writes the SQL that undoes the ones you didn't want. You review it and you run it. Undo a wrong change
- See a table as it was yesterday at 14:30, or every version of one row,
with
AS OFfrom your mysql client. Restore tables to a moment - Ask Claude what changed. Connect Claude, or any MCP client, and ask in plain words: "what was deleted from orders in the last hour?", "how did customer 42 look on Monday?", "give me the SQL that puts it back". Its tools only read, and it never runs SQL on your MySQL. Connect Claude
Where it runs
DBTrail reads your binlog over the replication protocol, the way a replica does. Nothing is installed on your MySQL: no plugin, no agent, no triggers. You don't move to another database or another cloud. DBTrail runs on your own machines, next to MySQL, Percona Server, MariaDB, Amazon RDS or Aurora, and the copy is plain Parquet files on your disk or in your S3 bucket.
Install
You need Docker with Compose, and the mysql client.
curl -fsSL https://raw.githubusercontent.com/dbtrail/dbtrail/main/install.sh | sh
It starts DBTrail and opens http://127.0.0.1:8090. Connect your MySQL in the form, take the first copy, turn on the MySQL port, and run a heavy query: the five steps are in the Quick Start.
For a server you keep running, the same setup as a compose file and a few API calls you can keep in your automation: In production. Linux packages and Amazon ECS too.
To try the time-travel SQL in 30 seconds, with nothing of yours connected:
docker run --rm -p 6033:6033 ghcr.io/dbtrail/bintrail-demo
(the demo image).
Limits
- The copy is behind your MySQL. By seconds in fresh mode, by minutes otherwise. A query that must see a write made a second ago belongs on your MySQL, and routing keeps transactions there.
- Lookups stay on your MySQL. A read by key takes a few milliseconds on MySQL and about 100 on the copy, so routing leaves it on your MySQL.
- Not high availability, and not your backup. Writes always go to your MySQL and nothing fails over to DBTrail. History starts the day you install it. Keep your replicas and your backups.
- Needs a ROW binlog with full row images (
binlog_format=ROW,binlog_row_image=FULL), and a primary key on every InnoDB table. The connect form checks the binlog settings and shows the fix. - Some schema changes re-read a table. Adding or dropping a column, or a
TRUNCATE, makes DBTrail read that table again, with a short lock. - Row history needs a bucket to last. Without S3 it keeps 48 hours. The copy itself stays.
- The MySQL port has no TLS yet. Use it on a private network.
- Yours to operate. DBTrail and its small index MySQL run on your machines. Disk, backups and upgrades are yours.
All of them: Limitations.
What it works with
| Source | Analytical copy | Row history and undo |
|---|---|---|
| MySQL 8.0, 8.4 | Yes | Yes |
| Percona Server for MySQL 8.0, 8.4 | Yes | Yes |
| Amazon RDS for MySQL | Yes (verified) | Yes (verified) |
| Amazon Aurora MySQL | Yes (verified) | Yes (verified) |
| Google Cloud SQL for MySQL | Should work, please report issues | Should work |
| MariaDB 10.11+, including Amazon RDS for MariaDB | Yes | Yes. See MariaDB source |
| PostgreSQL 14+ | One-time copy only, no scheduled update yet | Beta. See PostgreSQL source |
DBTrail never needs the binlog files on disk, which is why managed cloud databases work.
Who builds it
DBTrail is built by Daniel Guzman-Burgos, former MySQL Technical Lead at Percona.
Documentation
The guides live at dbtrail.com/docs. This repository keeps the reference for the command line and for operators:
Privacy
bintrail is DBTrail's command-line tool. It runs entirely in your
infrastructure. Your database data never leaves it: not your rows,
schemas, table names, queries, hostnames, DSNs, or file paths.
Official release builds do report metadata-only usage statistics: which command ran, whether it succeeded, a coarse error class, and your version and platform. It is on by default and turns off in one line:
bintrail telemetry off # or: DO_NOT_TRACK=1, BINTRAIL_TELEMETRY=off
bintrail telemetry show # prints what would be sent; sends nothing
No identifier of any kind is stored or transmitted, so nothing ties those statistics to you or your machine. A binary you build yourself has no reporting address compiled in and cannot send anything. TELEMETRY.md documents every field, every control, and the CI tests that enforce both.
The privacy policy covers the Claude Desktop extension (.mcpb),
which reports nothing at all, and how data moves when an AI client queries
your deployment.
License
Apache-2.0: free for any use, including commercial and production.
Contributions are welcome; see CONTRIBUTING.md. Each
commit carries a Signed-off-by line (DCO); git commit -s
adds it.
Want the index server operated for you (sized, backed up, upgraded, kept alive on-call) instead of running it yourself? That is the managed service at dbtrail.com. SUPPORT.md draws the ship-vs-operate line.
DBTrail MCP questions
How do I add DBTrail MCP to Claude Code?
Run claude mcp add --transport http bintrail https://api.dbtrail.com/mcp in your terminal. Add --scope user to make it available in every project.
How do I add DBTrail MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What can I ask an AI client to do with DBTrail?
You can ask in plain words what changed in your MySQL data, how a row looked at a past time, or for SQL that reverts an unwanted change. Its tools only read and never run SQL on your MySQL.
Does DBTrail install anything on my MySQL server?
No. DBTrail reads the binlog over the replication protocol like a replica, so no plugin, agent, or triggers are needed.
Can DBTrail undo a wrong change?
Yes. It keeps before and after images of every change and writes the SQL that undoes the changes you select. You review the generated SQL and run it yourself.
What binlog settings does DBTrail require?
It needs a ROW-format binlog with full row images and a primary key on every InnoDB table. The connect form checks these settings and shows the fix.
How up to date is the analytical copy?
The copy lags your MySQL by seconds in fresh mode and by minutes otherwise. Queries that must see a just-made write should stay on your MySQL.