dbgate-dashboard-mcp
An MCP server that gives an agent access to databases through a running DbGate dashboard. No database drivers are needed: DbGate itself holds the connections, engine plugins and pool, and the server talks to it over HTTP.
Engines: MySQL, PostgreSQL, SQLite (SQL tools), MongoDB and Redis (dedicated tools below).
Installation
// .mcp.json
{
"mcpServers": {
"dbgate-dashboard": {
"command": "uvx",
"args": ["dbgate-dashboard-mcp@latest"],
"env": {
"DBGATE_URL": "http://localhost:3000"
}
}
}
}
A remote dashboard through an SSH tunnel — DBGATE_URL then means the address on the remote side:
"env": {
"DBGATE_URL": "http://localhost:3000",
"SSH_PROXY_TO": "user@remote-host"
}
An HTTPS dashboard behind a reverse proxy works the same way — the port comes from the scheme (443), while Host and SNI stay canonical, so certificate verification is not disabled:
"env": {
"DBGATE_URL": "https://dbgate.example.com",
"SSH_PROXY_TO": "user@remote-host"
}
The tunnel only changes the connect address: DBGATE_URL is not rewritten, otherwise the proxy would receive Host: 127.0.0.1:<port> and answer with a redirect, and TLS would not match the certificate.
Tunnel loss
If ssh dies mid-session, the next call does not fail: the tunnel is reopened and the request is retried once. A second drop in a row is returned as an error, so an unreachable remote host does not send every tool into endless retries.
A reconnect is invisible by itself — a retried call looks like an ordinary one — so the tool result gets a notices field:
{
"connections": [ /* ... */ ],
"notices": [
"ssh tunnel dropped (ConnectError) and was reopened on 127.0.0.1:49173; the call was retried and this result is from the new connection"
]
}
The field appears only when there is something to report, and exactly once: the queue is drained when delivered.
Environment variables
| Variable | Default | Purpose |
|---|---|---|
DBGATE_URL |
http://localhost:3000 |
dashboard address (with a tunnel — the remote side) |
DBGATE_LOGIN |
— | login, if authentication is enabled in DbGate |
DBGATE_PASSWORD |
— | its password |
SSH_PROXY_TO |
— | user@host for the SSH tunnel (ssh -N -L) |
SSH_PROXY_PORT |
auto | fixed local port for the tunnel |
Tools
| Tool | What it does |
|---|---|
list_connections |
dashboard connections: conid, engine, default database |
list_databases |
databases on a connection |
list_tables |
tables, views and matviews (no columns) |
describe_table |
columns, PK, FKs and indexes of one object |
query |
a read query; appends LIMIT and truncates the result |
execute |
any SQL, including writes and DDL, unmodified |
find_documents |
documents of a Mongo collection with filter and sort |
redis_keys |
browse the Redis keyspace level by level |
redis_get |
type, TTL and value of one key |
redis_command |
any Redis command, including writes |
conid is required by every tool — take it from list_connections. database can be omitted: the connection's default database is used.
query limits the output twice: it appends LIMIT n if the SQL has no limit of its own, and in any case cuts the response to n rows (truncated: true when cut). The DbGate API has no limit parameter, so the bound has to be held on both sides.
LIMIT is appended only to statements that accept it (SELECT, WITH, VALUES, TABLE). SHOW, PRAGMA, DESCRIBE, EXPLAIN go to the engine as is — with a LIMIT glued on they would be a syntax error; cutting to n rows still applies to them.
execute passes SQL through unchanged and without a safety net — including INSERT/UPDATE/DELETE and DDL. Restrict permissions on the connection itself in DbGate.
MongoDB and Redis
find_documents takes a regular Mongo filter — {"artistId": {"$gt": 5}}, {"title": {"$regex": "Rock"}}, $in, $and/$or. It is translated into a DbGate condition, because the dashboard API does not accept a raw Mongo filter. An unsupported operator ($exists, $elemMatch) returns an explicit error. $regex becomes a LIKE wrapped in %…%, so % and _ inside the pattern act as wildcards.
Collections show up in the common list_tables with type: "collection"; describe_table for a collection returns the document count and the unique key — DbGate's Mongo structure has no columns.
Redis navigation has two levels: redis_keys without root shows prefixes (album, track, …), with root — the keys under it. redis_get reads a value as one page no longer than limit (truncated: true if the value continues); for the full data of a large key use redis_command, which runs an arbitrary command. For a missing key redis_get returns the error key '…' not found.
The command name in redis_command is case-insensitive — it is lowercased, because DbGate calls the method of the same name on its Redis client, and all those methods are lowercase.
A Redis connection has no default database, so database can be omitted: the server takes the first one in the list (db0). A freshly opened DbGate connection returns an empty database list while it starts up, so an empty answer is asked again — without that, database resolution sometimes failed with has no default database.
Development
uv sync # venv + runtime + dev group
uv run pytest # full suite; addopts enforces --cov-fail-under=100
uv run pytest tests/test_server.py --no-cov # partial run — only with --no-cov
python -m dbgate_dashboard_mcp # run over stdio
Tests need neither network nor a running DbGate: httpx and subprocess are faked.
Manual check on the test stand
The repository ships a docker-compose.yml with DbGate and five databases (Chinook in MySQL, PostgreSQL, SQLite, MongoDB, Redis). Seeds live in init/: Chinook (MIT, © Luis Rocha), adapted for each engine.
docker compose up -d
TOKEN=$(curl -s -X POST http://localhost:3000/auth/login \
-H 'Content-Type: application/json' -d '{"amoid":"none"}' \
| python3 -c 'import sys,json;print(json.load(sys.stdin)["accessToken"])')
curl -s -X POST http://localhost:3000/connections/list \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' -d '{}'
Then connect the server in an MCP client with DBGATE_URL=http://localhost:3000 and call list_connections.
How the DbGate API works
Useful when extending the server: DbGate is RPC over HTTP, not REST. Controller methods are mounted as kebab-case paths (queryData → /database-connections/query-data), almost all of them POST with a single JSON object of arguments. POST /auth/login {"amoid":"none"} issues a token that lives 24 h. SQL errors arrive with HTTP 200 and an errorMessage field, so success is decided by the response body, not the status code.
Metadata
Release files for dbgate-dashboard-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| dbgate_dashboard_mcp-0.1.0.tar.gz | 29.9 kB | With provenance | Details for dbgate_dashboard_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| dbgate_dashboard_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for dbgate_dashboard_mcp-0.1.0-py3-none-any.whl |
Total release size: 50.9 kB
Release files / dbgate_dashboard_mcp-0.1.0.tar.gz
| Download URL | dbgate_dashboard_mcp-0.1.0.tar.gz |
|---|---|
| Size | 29.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
980b64edb7c96c0e8656b08f0977e0a36065ff691f0416b71ed50d106814a00a
|
|
BLAKE2b-256 checksum How to use checksums |
26c7a789f3bb2cb0521bb637b684caac9e360330ca8caf44f8d60a9441ff2bc2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logRelease files / dbgate_dashboard_mcp-0.1.0-py3-none-any.whl
| Download URL | dbgate_dashboard_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 21.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4715b276c268afbe2e3ccb0ded82db885569f1531617420adb92edcc8e05b6e9
|
|
BLAKE2b-256 checksum How to use checksums |
ce95e407b1869ee84dd850e1ab4f5842622421bff1f39a1b409a2ddc4de425e9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logSecurity for dbgate-dashboard-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for dbgate_dashboard_mcp-0.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.