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:

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

Related MCP server: Database MCP Server

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:

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:

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):

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:

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):

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:

npm install -g dbeaver-connections-mcp

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:

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):

{
  "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):

{
  "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

{
  "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.

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 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

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:

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:

npm login
npm publish            # runs the tests first

License

MIT