# dbeaver-connections-mcp

An MCP server that lets AI assistants (Claude Code, Claude Desktop, GitHub Copilot in VS Code, Cursor...) explore your databases **through the connections you already have in DBeaver**. No second place to keep hosts and passwords.

Supported engines: **PostgreSQL** (and TimescaleDB, CockroachDB, YugabyteDB, Redshift), **MySQL**, **MariaDB**, **SQLite**, **SQL Server**, **Oracle** and **ClickHouse**. Connections behind an **SSH tunnel** work too. Other DBeaver connections are listed but marked as unavailable.

**Read-only by default, enforced by the database itself wherever the engine can do it:**

| Engine | How writes are refused |
|---|---|
| PostgreSQL, TimescaleDB, CockroachDB, YugabyteDB, Redshift | Every query runs in `BEGIN TRANSACTION READ ONLY` and is always rolled back |
| MySQL, MariaDB | Read-only session and `START TRANSACTION READ ONLY`, always rolled back. The session setting also refuses DDL, which would otherwise commit implicitly. |
| SQLite | The file is opened read-only, and an authorizer inside SQLite denies `ATTACH`, `VACUUM INTO`, writable pragmas and file functions |
| Oracle | `SET TRANSACTION READ ONLY`, always rolled back. Oracle refuses DML there; DDL would commit implicitly, so the SQL check keeps it out (and blocks autonomous transactions). |
| ClickHouse | Every query is sent with `readonly=1`: the server refuses writes, DDL and changing settings. ClickHouse has no transactions, so nothing needs rolling back. |
| SQL Server | **No read-only transaction exists.** Queries run in a transaction that is always rolled back, and the SQL check refuses everything but one `SELECT`. `list_connections` and `--check` warn about it; use a login that can only read, or set `DBEAVER_MCP_REQUIRE_DB_READONLY=true` to refuse these connections. |

Works with DBeaver Community Edition. DBeaver does not need to be running.

> Published on npm as `dbeaver-connections-mcp` (the npm name `dbeaver-mcp` belongs to an unrelated project). Installing it gives you the commands `dbeaver-connections-mcp`, `dbeaver-mcp` and `dbeaver-postgres-mcp`, which all start the same server.
>
> Earlier versions were called `dbeaver-postgres-mcp`. With `npx`, use the package name: `npx -y dbeaver-connections-mcp`. `npx -y dbeaver-mcp` would install the other project.

## What the assistant can do

| Tool | What it does |
|---|---|
| `list_connections` | Your DBeaver connections: name, engine, placeholder style, type (dev/test/prod), host, database, user, and how read-only is enforced. Never passwords. |
| `list_schemas` | Schemas with table counts and comments (MySQL, ClickHouse: databases; SQLite: `main`; Oracle: users that own tables) |
| `list_tables` | Tables and views with estimated row counts and comments. PostgreSQL partitions are folded into their parent. Filter by name or comment. |
| `describe_table` | Columns (type, nullable, default, comment), primary/unique/foreign/check constraints, tables that reference it, indexes, size, view definition. ClickHouse has no foreign or unique keys; it shows the primary, sorting and partition keys, `CHECK` constraints and data skipping indexes. |
| `find_columns` | Which tables have a column like `policy_id` |
| `run_query` | One read statement (`SELECT`, `WITH`, `VALUES`, plus `SHOW`/`TABLE` on PostgreSQL, `SHOW`/`DESCRIBE`/`TABLE` on MySQL and `SHOW`/`DESCRIBE`/`EXISTS` on ClickHouse), with parameters, row limit and shortened long values. Placeholders follow the engine: `$1` on PostgreSQL, `?` on MySQL, MariaDB and SQLite, `@p1` on SQL Server, `:1` on Oracle, typed `{p1:String}` / `{p1:UInt64}` on ClickHouse. |
| `explain_query` | Query plan; `analyze: true` runs it (still read-only) for real timings. SQLite has no timings and shows the plan only. SQL Server uses `SHOWPLAN_TEXT` / `STATISTICS PROFILE`; Oracle uses `EXPLAIN PLAN` (rolled back) and, for `analyze`, `DBMS_XPLAN.DISPLAY_CURSOR`, which needs `SELECT_CATALOG_ROLE`. CockroachDB uses its own `EXPLAIN` / `EXPLAIN ANALYZE`; Redshift has no `analyze`. ClickHouse shows `EXPLAIN indexes = 1`; with `analyze` it also runs the query (read-only, results discarded) and adds rows and bytes read, time and memory. |
| `execute_sql` | **Only when `DBEAVER_MCP_ALLOW_WRITE=true`**, and never on prod or read-only connections |

## Install and connect

Requires Node.js 20+. SQLite connections need Node.js 22.13+ (they use Node's built-in `node:sqlite`, so nothing native is installed). SQL Server uses `tedious` and Oracle uses `oracledb` in Thin mode, both pure JavaScript; no Oracle Instant Client is needed. `oracledb` is an optional dependency: if it is missing, Oracle connections are listed as unavailable. ClickHouse uses `@clickhouse/client` over ClickHouse's HTTP interface (port 8123, or 8443 with TLS); connections set to the native port 9000 are listed as unavailable. SSH tunnels use `ssh2`, also an optional dependency.

Check first what it sees and whether it can log in:

```bash
npx -y dbeaver-connections-mcp --check
```

```
workspace: C:\Users\you\AppData\Roaming\DBeaverData\workspace6
- Local Insurance [dev] localhost:5432/insurance user=qa, password saved
    OK: connected as qa, PostgreSQL 16.4
- Shop [dev] localhost:3306/shop user=app, password saved
    OK: connected as app@%, MySQL 8.4.6
- Local cache [dev] C:\data\cache.db
    OK: SQLite 3.51.2
- Analytics [prod] warehouse:1521/dwh user=bi, password saved
    OK: connected as BI, Oracle 19.24.0.0.0; read-only enforced by: a read-only transaction (DDL is kept out by the SQL guard)
- Billing [test] sql01:1433/billing user=report, password saved
    OK: connected as report, SQL Server 16.0.4305.5 (Standard Edition (64-bit)); read-only enforced by: the SQL guard and a rollback only
- Events [dev] clickhouse:8123/events via SSH deploy@bastion.example.com:22 user=reader, password saved
    OK: connected as reader, ClickHouse 25.8.4.13; read-only enforced by: the database
- Ledger [test] crdb.internal:26257/ledger user=app, password saved
    OK: connected as app, CockroachDB v25.4.17; read-only enforced by: the database
- Legacy ERP [prod] erp:5000/erp user=sa, password saved
    NOT USABLE: generic is not supported yet (supported: postgresql, mysql, sqlite, sqlserver, oracle, clickhouse)
mode: read-only
```

### Claude Code

macOS / Linux:

```bash
claude mcp add dbeaver --scope user -- npx -y dbeaver-connections-mcp
```

Windows (Claude Code cannot start `npx` directly there, so it goes through `cmd /c`):

```bash
claude mcp add dbeaver --scope user -- cmd /c npx -y dbeaver-connections-mcp
```

`--scope user` makes the server available in every folder. Without it, `claude mcp add` registers it only for the folder you ran it in. Check that it starts with:

```bash
claude mcp get dbeaver
```

It should say `Status: ✓ Connected`. The very first check can say `Failed to connect` while `npx` is still downloading the package; run it again. If it says Connected but the assistant sees no connections, run `npx -y dbeaver-connections-mcp --check`: if DBeaver keeps its workspace somewhere unusual, set `DBEAVER_WORKSPACE`.

Limit it to some connections (on Windows, put `cmd /c` before `npx` as above):

```bash
claude mcp add dbeaver --scope user -e DBEAVER_MCP_CONNECTION_TYPES=dev,test -- npx -y dbeaver-connections-mcp
```

#### If `claude mcp add` says `unknown option '-y'`

Some setups lose the `--`, and then `claude mcp add` reads the `-y` meant for `npx` as its own option. Any of these avoids it:

**Install globally and run it with `node`.** No `npx` or `-y`, and it starts faster because nothing is downloaded at launch. `npm root -g` prints where global packages live; use that folder in the path:

```bash
npm install -g dbeaver-connections-mcp
```

```bash
claude mcp add dbeaver --scope user -- node "C:\Users\you\AppData\Roaming\npm\node_modules\dbeaver-connections-mcp\dist\index.js"
```

On macOS / Linux the global install puts `dbeaver-connections-mcp` on your `PATH`, so `claude mcp add dbeaver --scope user -- dbeaver-connections-mcp` is enough. To update, run `npm install -g dbeaver-connections-mcp` again.

**Pass the command as JSON**, so its arguments are never read as options:

```bash
claude mcp add-json dbeaver --scope user '{"type":"stdio","command":"cmd","args":["/c","npx","-y","dbeaver-connections-mcp"]}'
```

(On macOS / Linux use `"command":"npx","args":["-y","dbeaver-connections-mcp"]`.) Windows PowerShell 5.1 can strip the inner double quotes; if you get a JSON error, use one of the other two ways.

**Write the config file yourself.** `.mcp.json` in a project folder makes the server available in that project (Claude Code asks you to approve it the first time):

```json
{
  "mcpServers": {
    "dbeaver": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "dbeaver-connections-mcp"],
      "env": { "DBEAVER_MCP_CONNECTION_TYPES": "dev,test" }
    }
  }
}
```

After a global install you can use `"command": "node"` with `"args": ["C:\\Users\\you\\AppData\\Roaming\\npm\\node_modules\\dbeaver-connections-mcp\\dist\\index.js"]` instead. For every folder, put the same `mcpServers` entry in `~/.claude.json`.

Then check with `claude mcp get dbeaver` as above.

### GitHub Copilot in VS Code

`.vscode/mcp.json` in your project (or the user-level MCP config):

```json
{
  "servers": {
    "dbeaver": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "dbeaver-connections-mcp"],
      "env": { "DBEAVER_MCP_CONNECTION_TYPES": "dev,test" }
    }
  }
}
```

Use Copilot Chat in **Agent** mode to call the tools.

### Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "dbeaver": {
      "command": "npx",
      "args": ["-y", "dbeaver-connections-mcp"]
    }
  }
}
```

Claude Desktop: `claude_desktop_config.json`. Cursor: Settings → MCP.

## Configuration

All settings are environment variables, so they work in any MCP client.

| Variable | Default | |
|---|---|---|
| `DBEAVER_WORKSPACE` | auto | Folder that contains `General`. Auto-detected for Windows, macOS, Linux, Flatpak and Snap installs. |
| `DBEAVER_PROJECTS` | all | Only these DBeaver projects, comma separated |
| `DBEAVER_MCP_CONNECTIONS` | all | Only these connections (name, id, or `project/name`) |
| `DBEAVER_MCP_EXCLUDE` | none | Hide these connections |
| `DBEAVER_MCP_CONNECTION_TYPES` | all | Only these DBeaver connection types, e.g. `dev,test` |
| `DBEAVER_MCP_ALLOW_WRITE` | `false` | `true` adds `execute_sql` |
| `DBEAVER_MCP_REQUIRE_DB_READONLY` | `false` | `true` refuses connections whose engine cannot enforce read-only itself (SQL Server) |
| `DBEAVER_MCP_DEFAULT_ROWS` | `100` | Rows returned when the model does not ask for a number |
| `DBEAVER_MCP_MAX_ROWS` | `1000` | Hard limit per query |
| `DBEAVER_MCP_TIMEOUT_MS` | `30000` | Time limit for every query (`statement_timeout`, `max_execution_time` / `max_statement_time`; SQLite, SQL Server and Oracle queries are cancelled by the client). Schema exploration gets at least 15 s, because some dictionaries (Oracle's) are slow. |
| `DBEAVER_MCP_KNOWN_HOSTS` | `~/.ssh/known_hosts` | Known host keys for SSH tunnels (see below) |
| `DBEAVER_MCP_SSH_ACCEPT_UNKNOWN_HOSTS` | `false` | `true` accepts SSH servers not listed in known_hosts |
| `DBEAVER_MCP_MAX_CELL_CHARS` | `500` | Longer text/JSON values are cut |

The workspace is re-read every few seconds, so a connection you add in DBeaver is visible without restarting.

### What is taken from DBeaver

- Host, port, database or SQLite file (also from the JDBC URL when the connection is saved in URL mode), SQL Server named instances, Oracle service name / SID / TNS alias (`tnsnames.ora` from DBeaver's TNS path or `TNS_ADMIN`)
- Saved user and password (`credentials-config*.json`)
- Connection type (dev / test / prod, and custom types with "confirm execute")
- The "Read-only connection" checkbox
- SSL settings with root/client certificates (PEM): PostgreSQL `sslmode`; MySQL `sslMode` / `useSSL` / `verifyServerCertificate` (like Connector/J, TLS is tried first by default); SQL Server `encrypt` / `trustServerCertificate` (encrypted by default, like the Microsoft JDBC driver); ClickHouse `ssl` / `sslmode`. They are read from the JDBC URL query string (`?sslmode=verify-full`), driver properties and the SSL tab, each overriding the one before
- Default schema (bootstrap setting): the search path on PostgreSQL, the default database on MySQL, `CURRENT_SCHEMA` on Oracle
- ClickHouse: the database, and HTTPS from the JDBC driver's `ssl` / `sslmode` / `sslrootcert` properties or the SSL tab
- **SSH tunnel** (SSH tab, or a network profile): host and port, password, private key file or saved key (with its passphrase), or SSH agent (`SSH_AUTH_SOCK`; Pageant or the Windows OpenSSH agent), one jump server, and the "remote host/port" override. Each connection gets a local port on `127.0.0.1` forwarded through the SSH server, opened on first use and reopened if it drops. Host keys are checked against `~/.ssh/known_hosts`: a host listed with a different key, or with a key marked `@revoked`, is refused. An unlisted host is refused too (DBeaver would ask, this server cannot): connect once with `ssh` to add it, set `DBEAVER_MCP_SSH_ACCEPT_UNKNOWN_HOSTS=true`, or set "Bypass host verification" in DBeaver to skip the check. A `known_hosts` that exists but cannot be read is an error. TLS to the database is still checked against the real host name where the client library allows it (PostgreSQL, SQL Server, ClickHouse).

PostgreSQL-compatible servers use DBeaver's PostgreSQL driver entries (TimescaleDB, CockroachDB, YugabyteDB, Redshift, Greenplum, EDB...). Which one is behind a connection is read from `version()`, so a CockroachDB cluster opened with the plain PostgreSQL driver works too. TimescaleDB, CockroachDB and YugabyteDB are tested; Redshift is not (there is no Redshift to run in Docker): its catalog is PostgreSQL 8.0's, so the server leaves out what Redshift lacks (`lock_timeout`, partitions, identity columns, relation sizes, `EXPLAIN ANALYZE`). Google Cloud SQL connector connections are listed as unavailable.

If a PostgreSQL connection has no saved password, or the project uses DBeaver's "secure storage" (OS keychain), the server falls back to the normal PostgreSQL ways: `PGPASSWORD` and `~/.pgpass` (`%APPDATA%\postgresql\pgpass.conf` on Windows). MySQL connections without a saved password log in without one.

SQL Server: SQL Server logins only (Windows, Kerberos and Entra ID authentication are listed as unavailable). Oracle: normal database logins only; connections set to log in as SYSDBA/SYSOPER are refused.

**Not supported yet:** SOCKS/HTTP proxies (those connections are listed as unavailable), more than one SSH jump server, keyboard-interactive SSH logins other than a saved password, and engines other than the ones above. See [docs/multi-db-plan.md](docs/multi-db-plan.md) for what comes next; a new engine is one class implementing `Driver` in `src/drivers/types.ts`.

## Safety

Layers, from strongest to weakest:

1. **Read-only in the database, always rolled back** (see the table at the top). On PostgreSQL, MySQL, MariaDB and SQLite, writes, DDL, data-modifying CTEs and `SELECT INTO` all fail inside the engine; on Oracle, DML does. The test suite checks this per engine with the SQL check switched off, and checks that SQL Server's rollback undoes writes and DDL.
2. **Static SQL check**, per dialect. It understands each engine's quoting and comments, including MySQL's `/*! ... */` comments, which the server executes. It allows one statement per call and no transaction control, and it blocks the few things a read-only transaction does not stop:
   - PostgreSQL: `dblink*` (opens a second connection), server files (`pg_read_file`, `lo_import`...), admin functions (`pg_terminate_backend`, `set_config`...), password tables (`pg_authid`, `pg_shadow`)
   - MySQL / MariaDB: `INTO OUTFILE` / `DUMPFILE`, `LOAD DATA`, `LOAD_FILE()`, `SLEEP()` / `BENCHMARK()` / locks, `SET` / `USE` (session state of pooled connections), `KILL`, `mysql.user`
   - SQLite: `ATTACH`, `VACUUM`, `load_extension()` and file functions (SQLite's authorizer also denies them)
   - SQL Server: anything but one `SELECT` / `WITH`. SQL Server runs statements sent without `;` as one batch (`SELECT 1 DELETE FROM t`), so in read-only mode the check refuses every other statement's first word anywhere (`INSERT`, `EXEC`, `INTO`, `COMMIT`, `SET`...; quote a column named like a keyword). Also `xp_*`, `sp_OA*`, `OPENROWSET` / `OPENQUERY` / `OPENDATASOURCE`, dynamic SQL, `WAITFOR`, `NEXT VALUE FOR`, login tables.
   - ClickHouse: table functions and functions that reach other servers, object stores or the server's files (`url`, `s3`, `remote`, `mysql`, `postgresql`, `file`, `executable`...; `readonly=1` already refuses most of them), `sleep`, `SET` / `USE` / `SYSTEM` / `KILL`, `INTO OUTFILE`, `system.named_collections` (holds credentials). A `SETTINGS` clause in the query is refused by the server itself under `readonly=1`, so the time limit cannot be lifted.
   - Oracle: DDL, PL/SQL blocks, `WITH FUNCTION` and `PRAGMA AUTONOMOUS_TRANSACTION`, `ALTER SESSION`, packages that reach files, the network, other sessions or jobs (`UTL_FILE`, `UTL_HTTP`, `DBMS_LOCK`, `DBMS_SQL`, `DBMS_SCHEDULER`...), `SYS.USER$` / `LINK$`. A stored function that itself uses an autonomous transaction cannot be detected; a read-only login prevents that.
3. **Timeouts and limits.** Every query has a time limit and lock timeouts. Row caps stop on the server side: a cursor on PostgreSQL, `sql_select_limit` on MySQL, stepping the statement on SQLite, `SET ROWCOUNT` on SQL Server, fetching only the rows needed on Oracle, and `max_result_rows` with `result_overflow_mode=break` plus a streamed read on ClickHouse. Big tables are never pulled into memory.
4. **Write mode is opt-in** and still refuses prod-like and DBeaver read-only connections.

What you should still do:

- **Use a database user with SELECT-only grants** for the connections you expose. That is the only protection that does not depend on this code, and on SQL Server it is the only one in the database at all.
- Remember that query results are sent to your AI provider. Check this is allowed for the data (personal data, client data).
- DBeaver's password file is encrypted with a key that is the same in every installation. This tool reads it the same way DBeaver does, and so can any program running as you. The server never returns passwords to the model.

## Development

```bash
npm install
npm run build
npm test                     # unit tests
npm run inspect              # MCP Inspector UI
```

`npm test` always runs the unit tests and the SQLite conformance tests, which build their own database file. Tests for the other engines run when that database is available and loaded with the matching fixture. `test/compose.yml` starts all of them:

```bash
docker compose -p dbeaver-mcp-test -f test/compose.yml up -d
# Oracle takes a minute or two on first start.
docker exec -i dbeaver-mcp-test-postgres-1 psql -U postgres < test/fixture.sql
docker exec -i dbeaver-mcp-test-mysql-1 mysql -uroot -proot < test/fixture.mysql.sql
docker exec -i dbeaver-mcp-test-mariadb-1 mariadb -uroot -proot < test/fixture.mysql.sql
docker cp test/fixture.mssql.sql dbeaver-mcp-test-mssql-1:/tmp/f.sql
docker exec dbeaver-mcp-test-mssql-1 /opt/mssql-tools18/bin/sqlcmd -C -S localhost -U sa -P 'Sa_passw0rd!' -i /tmp/f.sql
docker cp test/fixture.oracle.sql dbeaver-mcp-test-oracle-1:/tmp/f.sql
docker exec dbeaver-mcp-test-oracle-1 sqlplus -s system/oracle@//localhost/FREEPDB1 @/tmp/f.sql
docker exec -i dbeaver-mcp-test-clickhouse-1 clickhouse-client --password clickhouse --multiquery < test/fixture.clickhouse.sql
docker exec -i dbeaver-mcp-test-timescale-1 psql -U postgres < test/fixture.sql
docker exec -i dbeaver-mcp-test-cockroach-1 ./cockroach sql --insecure -d defaultdb < test/fixture.cockroach.sql
docker exec -i dbeaver-mcp-test-yugabyte-1 bash -c 'bin/ysqlsh -h $(hostname) -U yugabyte' < test/fixture.sql
TEST_PG_HOST=localhost TEST_PG_PORT=15432 PGPASSWORD=postgres TEST_MYSQL=localhost:13306 TEST_MARIADB=localhost:13307 \
  TEST_MSSQL=localhost:11433 TEST_ORACLE=localhost:11521 TEST_CLICKHOUSE=localhost:18123 \
  TEST_TIMESCALE=localhost:15433 TEST_COCKROACH=localhost:16257 TEST_YUGABYTE=localhost:15434 \
  TEST_SSH=localhost:12222 npm test
```

(`podman` works the same as `docker`. In Git Bash on Windows, set `MSYS_NO_PATHCONV=1` for the `docker cp` / `exec` lines.) `src/conformance.test.ts` runs the same checks against every engine, and with `TEST_SSH` once more for each engine through the compose `ssh` service (an OpenSSH server that reaches the databases by their service names). `src/integration.test.ts` has the PostgreSQL-specific ones, and `src/ssh.test.ts` tests tunnels against in-process SSH servers (password, keys, jump server, `known_hosts`), so it needs no Docker.

Publishing:

```bash
npm login
npm publish            # runs the tests first
```

## License

MIT