Skip to main content
Glama
dbgate-dashboard

dbgate-dashboard

by danilin-em

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.

Related MCP server: AKIMCP

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes a governed, OAuth-gated suite of 38 tools that let web AI assistants like Claude, ChatGPT, and Grok work directly on your local machine — reading and editing files, running whitelisted shell commands, searching, querying SQLite, driving browsers and DevTools, managing background tasks and localhost services, and controlling Git, clipboard, notifications, and Postman. This lets users build, debug, and maintain projects, inspect databases and local APIs, and check on long-running jobs from a browser or phone without granting unrestricted shell access.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Connects web-based AI chat clients such as Claude, ChatGPT, and Grok to a local machine through a single OAuth-gated MCP endpoint so they can browse, read, write, and edit files, run whitelisted shell commands, search content, use Git, query SQLite, drive browsers and DevTools, and manage background tasks, ports, and clipboard. It also exposes localhost and LAN services via a protected HTTP client, letting remote or mobile clients debug and operate local projects without granting unrestricted shell access.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Exposes a governed suite of 38 tools over a single OAuth-gated MCP endpoint, letting web-based AI chat clients read and edit local files, run whitelisted shell commands, search, use Git, inspect SQLite databases, and drive browser, DevTools, clipboard, and background-task workflows. It requires no system-wide install or admin rights and restricts access to folders and commands approved from a local control panel.
      MIT