dbngin-mcp
# dbngin-mcp
An MCP server (stdio, zero runtime dependencies) that controls local database services managed by **[DBngin](https://dbngin.com/)** (TablePlus) on **Windows**: start / stop / restart, live status and logs for **PostgreSQL** and **Redis** — driven by your AI agent through the [Model Context Protocol](https://modelcontextprotocol.io/).
The MCP protocol is implemented directly as newline-delimited JSON-RPC 2.0 over stdio — no SDK, no `npm install`, one file.
## Why
DBngin is a great GUI for managing local database engines, but agents (ZCode, Claude Desktop, Cursor, …) can't click its UI. This server exposes DBngin services as MCP tools, so an agent can:
- discover which services exist and **whether they are actually running** (live TCP port probe, not the GUI's possibly stale status field);
- start a service before running migrations/tests and stop it afterwards;
- inspect a service (PID, uptime, process name, Redis PING) and read its log tail when something fails.
## Requirements
- **Windows** (uses `netstat`, `tasklist`, `taskkill`, `pg_ctl` and PowerShell for process/port details)
- **Node.js** 18+
- [DBngin](https://dbngin.com/) installed, with at least one service created
- PostgreSQL / Redis engines downloaded through the DBngin app (start/stop is implemented for these two types)
## Setup
Clone this repo anywhere and register it in your MCP client's config:
```json
{
"mcpServers": {
"dbngin": {
"type": "stdio",
"command": "node",
"args": ["C:\\path\\to\\dbngin-mcp\\index.js"],
"timeoutMs": 60000
}
}
}
```
There is nothing to install — the server has zero runtime dependencies.
## Tools
| Tool | Description |
|---|---|
| `list_services` | List every service from `DBEngines.json` with its live running state (TCP port probe), type, version, port and paths. Call this first. |
| `start_service` | Start a service. PostgreSQL: `postgres.exe` spawned detached with the same command line the DBngin app uses. Redis: hidden detached `redis-server`. Waits until the port answers (up to 15 s). Returns `already_running` without failing if the service is up. |
| `stop_service` | Stop a service. PostgreSQL: `pg_ctl stop -m fast`. Redis: `SHUTDOWN NOSAVE` via `redis-cli`, with a `taskkill` fallback **only** after confirming the port owner is `redis-server.exe`. Returns `already_stopped` without failing if the service is down. |
| `restart_service` | `stop_service` followed by `start_service`. Prefer `start_service` for a stopped service. |
| `service_status` | Live detail for one service: running state, PID, process name, port answering, Redis PING, uptime / started-at, data / binaries / log paths. Works for every engine type (port-probe based outside postgresql/redis). |
| `get_logs` | Last N lines (default 50, max 1000) of a service log. PostgreSQL: `<dataDir>\pg_log.log`. Redis: the log file written under `Engines\redis` when started through this server. |
## Targeting a service
Every service tool accepts `name` (case-insensitive) plus optional `type`, or an `id` from `list_services`:
```json
{"name": "myapp", "type": "redis"}
{"id": "fc0f85c5-a573-4c7c-8b6b-211d842d4ef0"}
```
Service names are **not unique** in DBngin (two services can share a name with different engine types). Without `type`/`id`, an ambiguous name fails with the candidate list.
## Engine support
| Engine | Start/stop | Status | Logs |
|---|---|---|---|
| PostgreSQL | ✅ | ✅ (`pg_ctl` + port probe) | ✅ (`<dataDir>\pg_log.log`) |
| Redis | ✅ | ✅ (port probe + `PING`) | ✅ (`Engines\redis\redis_<port>.log`) |
| MySQL, MariaDB, MongoDB, Elasticsearch | ❌ (clear error; start from the DBngin app) | ✅ (port probe) | ❌ |
PostgreSQL details:
- The start command replicates what DBngin itself runs (`postgres.exe -D <DBPath> -p <port>`), launched detached via PowerShell `Start-Process -WindowStyle Hidden` so workers inherit a single hidden console and the server survives the MCP process exiting.
- `pg_ctl start -l` is intentionally avoided: it opens the log with exclusive sharing and can deadlock startup after an unclean shutdown.
- Stop and status use the `pg_ctl.exe` from that engine version's own `BinPath`.
Redis details:
- Started with the same flags the DBngin app uses (`--save "" --appendonly no --maxmemory 256mb --maxmemory-policy allkeys-lru`), **plus** `--bind 127.0.0.1` so the dev server never leaves loopback.
- Dumps and logs live under `%LOCALAPPDATA%\com.tinyapp.DBngin\Engines\redis`; one log file per port.
- Detached — survives the MCP server exiting.
## Safety notes
- The server **never writes** `DBEngines.json` or any DBngin configuration. The only files it creates are the Redis dumps dir and Redis log under `Engines\redis`.
- Running state comes from a real TCP probe on `127.0.0.1` (with `pg_ctl status` / Redis `PING` as reinforcement), not from the GUI status field.
- Before sending `SHUTDOWN`, the server verifies the port owner's process image; it refuses to stop an unrelated process.
- All processes are started hidden — no console windows flash.
- Engines other than PostgreSQL/Redis are inspect-only; start/stop returns a clear error instead of guessing.
## Troubleshooting
- **"Cannot read the DBngin config"** — DBngin isn't installed (or never ran). Config lives at `%LOCALAPPDATA%\com.tinyapp.DBngin\Data\DBEngines.json`.
- **Postgres "port did not answer"** — startup after an unclean shutdown can take longer than the 15 s wait; check `pg_log.log` (`get_logs`) and retry.
- **Redis PIDs don't show in netstat** — the RedisWindows build keeps its socket in the `Bind` state, which netstat doesn't list as `LISTENING`. The server falls back to PowerShell `Get-NetTCPConnection` and uses a `PING` as secondary proof.
## Development
Everything lives in a single `index.js`. Run it directly and speak MCP to it:
```
node index.js
```
or smoke-test the handshake:
```
echo {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}} | node index.js
```
Built and tested on Windows 11 (Windows Terminal as default terminal). macOS/Linux are not supported — DBngin's Windows data layout and the process helpers used here are Windows-specific.
## License
[MIT](LICENSE)
TDQS
Scored across 6 tools
Each tool has a distinct role: lifecycle actions (start/stop/restart), discovery (list_services), diagnostics (service_status), and log retrieval. The only mild overlap is list_services vs service_status since both surface running state, but descriptions clarify the former is for discovery and the latter for detailed per-service inspection.
All names are snake_case and mostly follow a verb_noun pattern (list_services, start_service, stop_service, restart_service, get_logs). Minor deviations: service_status puts the noun first instead of a verb, and get_logs uses a different verb style than list_services for a read operation.
Six tools is well-scoped for a local database service manager, covering exactly the discovery, lifecycle, and diagnostics operations an agent needs. No tool feels redundant or superfluous.
The surface covers the full service lifecycle (list, start, stop, restart, status, logs) with no dead ends for managing existing services. Minor gaps exist — no tool to create/register a new service or edit configuration/data paths, but core operational workflows are fully supported.