dbeaver-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, MySQL, MariaDB, SQLite, SQL Server and Oracle. 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.

Formerly published as dbeaver-postgres-mcp. The dbeaver-postgres-mcp command still works as an alias of dbeaver-mcp.

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.

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

npx -y dbeaver-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
- Legacy ERP [prod] erp:5000/erp user=sa, password saved
    NOT USABLE: mssql is not supported yet (supported: postgresql, mysql, sqlite, sqlserver, oracle)
mode: read-only

Claude Code

claude mcp add dbeaver -- npx -y dbeaver-mcp

On Windows: claude mcp add dbeaver -- cmd /c npx -y dbeaver-mcp

Limit it to some connections:

claude mcp add dbeaver -e DBEAVER_MCP_CONNECTION_TYPES=dev,test -- npx -y dbeaver-mcp

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

• Default schema (bootstrap setting): the search path on PostgreSQL, the default database on MySQL, CURRENT_SCHEMA on Oracle

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: SSH tunnels and proxies (those connections are listed as unavailable), and engines other than the six 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.

   • 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, and fetching only the rows needed on Oracle. 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
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 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; src/integration.test.ts has the PostgreSQL-specific ones.

Publishing:

npm login
npm publish            # runs the tests first

License

MIT