# @mhdd_24/dbeaver-mcp

[![npm version](https://img.shields.io/npm/v/%40mhdd_24%2Fdbeaver-mcp.svg)](https://www.npmjs.com/package/@mhdd_24/dbeaver-mcp)
[![GitHub](https://img.shields.io/badge/GitHub-Mhdd--24%2FDBeaver--MCP-blue)](https://github.com/Mhdd-24/DBeaver-MCP)

MCP server for **PostgreSQL / DBeaver-style** exploration and SQL from [Cursor](https://cursor.com) (or any MCP client). Same architecture as [@mhdd_24/pgadmin-mcp](https://github.com/Mhdd-24/PgAdmin-MCP).

Say **"db status"**, **"list databases"**, or **"run this SQL on Dev"** in chat — the assistant calls the matching tools.

**Full documentation:** [docs/WIKI.md](./docs/WIKI.md)

---

## Tools

| Tool | Role |
|------|------|
| `db_set_profile` | Sticky session switch: `dev` \| `qa` \| `default` |
| `db_status` | Sticky + active profile, host, `SELECT 1` |
| `db_list_databases` | List databases on active (or one-shot) profile server |
| `db_list_schemas` | List user schemas |
| `db_list_tables` | List tables/views in a schema |
| `db_describe_table` | Column metadata |
| `db_query` | Run SQL (read-only by default) |

### Profiles (no connection details in chat)

1. Put **both** Dev and QA credentials in `mcp.json` (`DBEAVER_DEV_*`, `DBEAVER_QA_*` — or reuse `PG_DEV_*` / `PG_QA_*`).
2. Say **`dbprofile=qa`** or **`dbprofile=dev`** — the assistant calls `db_set_profile`.
3. Later tools reuse that sticky profile until you switch or the MCP process restarts.
4. Optional one-shot: pass `profile: "qa"` on a single tool without changing sticky.
5. `database` still means the logical DB name on that server (e.g. `transboard`), not the env profile.

---

## Safety

- **Read-only by default** — only `SELECT` / `WITH…SELECT` / `EXPLAIN` / `SHOW` / `VALUES`
- Set `DBEAVER_ALLOW_WRITE=true` (or `PG_ALLOW_WRITE=true`) to allow writes
- `DBEAVER_QUERY_MAX_ROWS` / `PG_MAX_ROWS` caps returned rows; timeout via `DBEAVER_STATEMENT_TIMEOUT_MS` / `PG_QUERY_TIMEOUT_MS`

---

## Install / run

```bash
npm i -g @mhdd_24/dbeaver-mcp
# or from source:
git clone https://github.com/Mhdd-24/DBeaver-MCP.git
cd DBeaver-MCP
npm install
npm run build
node dist/index.js
```

---

## Cursor `mcp.json`

```json
"dbeaver": {
  "command": "npx",
  "args": ["-y", "@mhdd_24/dbeaver-mcp"],
  "env": {
    "DBEAVER_PROFILE": "dev",
    "DBEAVER_DEV_HOST": "192.168.1.141",
    "DBEAVER_DEV_PORT": "5432",
    "DBEAVER_DEV_USER": "postgres",
    "DBEAVER_DEV_PASSWORD": "YOUR_PASSWORD",
    "DBEAVER_DEV_DATABASE": "postgres",
    "DBEAVER_QA_HOST": "192.168.1.131",
    "DBEAVER_QA_PORT": "5432",
    "DBEAVER_QA_USER": "postgres",
    "DBEAVER_QA_PASSWORD": "YOUR_PASSWORD",
    "DBEAVER_QA_DATABASE": "postgres",
    "DBEAVER_ALLOW_WRITE": "false",
    "DBEAVER_QUERY_MAX_ROWS": "500"
  }
}
```

Restart Cursor after saving.

---

## Example prompts

- dbprofile=qa
- dbprofile=dev
- db status
- list databases
- list tables in schema transc for database transboard
- describe table translations schema transc database transboard
- run: SELECT version();