Skip to main content
Glama
README.md
# 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

A4/5.0

Scored across 6 tools

Disambiguation4/5

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.

Naming Consistency4/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues