Skip to main content

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)

Source distribution for dbgate-dashboard-mcp 0.1.0
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)

Table of built distributions (wheels) for dbgate-dashboard-mcp 0.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page