dbeaver-mcp

MCP server that exposes your DBeaver connections to Claude as tools. Decrypts credentials in memory — never persists passwords to disk.

Read in Chinese

Use your existing DBeaver database connections directly from Claude Code to query, manage, and analyze MySQL, PostgreSQL, and Oracle databases without re-entering credentials.

How It Works

┌─────────────────────────┐
│       Claude Code       │
└───────────┬─────────────┘
            │ MCP stdio (JSON-RPC 2.0)
            │ Only tool calls flow here — never raw credentials
            ▼
┌─────────────────────────────────────────────┐
│          dbeaver-mcp (Node.js)              │
│                                             │
│  1. Reads DBeaver's config files from disk   │
│  2. Decrypts credentials in memory only      │
│     (MySQL/mysql2, PostgreSQL/pg,           │
│      Oracle/oracledb, Redis/ioredis)        │
│  3. Returns query results to Claude          │
│  4. Closes connection — nothing persisted   │
└──────┬──────────────────────────┬──────────┘
       │                          │
       ▼                          ▼
  DBeaver workspace         Database server
  (data-sources.json,       (MySQL, PostgreSQL,
   credentials-config.json)  Oracle, Redis)

Step by step

1. Claude sends a tool call (e.g. run_query with connection name + SQL) over MCP stdio. The MCP protocol only carries the tool name and arguments — no credentials.

2. dbeaver-mcp resolves the connection by reading DBeaver's data-sources.json to find host, port, and database. It uses a fuzzy name matcher so you don't need exact IDs.

3. Credentials are decrypted in memory. DBeaver 21+ encrypts credentials-config.json with AES-128-CBC (file-level encryption). dbeaver-mcp reads the binary file, extracts the IV (first 16 bytes), decrypts the rest with DBeaver's built-in key, and parses the JSON. The decrypted password exists only as a variable in memory — never written to disk, logs, or stdout.

4. A direct database connection is opened using mysql2, pg, or oracledb depending on the driver type. The connection is used for a single operation.

5. The query executes and results are returned as JSON through MCP stdout. Only the query results flow back to Claude — never the password or connection credentials.

6. The connection is closed immediately after the query. No connection pool, no background process holding credentials.

Why It's Secure

Credentials never leave your machine

❌ What dbeaver-mcp does NOT do:
   • Send passwords to Claude/Anthropic servers
   • Write passwords to disk, logs, or environment variables
   • Keep passwords in memory after the query completes
   • Expose passwords through the MCP protocol

✅ What happens instead:
   • Passwords are read from DBeaver's encrypted file
   • Decrypted in a local variable for the duration of one query
   • Used to open a direct MySQL connection from YOUR machine
   • Garbage collected after the connection closes

Defense in depth — 5 layers of protection

What Claude sees vs. what it doesn't

Source code is open

Every line of the credential handling is in src/dbeaver.ts. The decryption function is ~10 lines. There are no network calls, no telemetry, no external services. You can audit it in minutes.

Installation

One-time setup

Step 1: Clone and build

git clone https://github.com/ALinCheung/dbeaver-mcp.git ~/.claude/skills/dbeaver-mcp
cd ~/.claude/skills/dbeaver-mcp
npm cache clean --force
npm install && npm run build
npm link

Step 2: Verify installation

npx dbeaver-mcp --version

Step 3: Register MCP server

Add the following to ~/.claude.json (Claude Code) or ~/.config/opencode/opencode.json (OpenCode):

{
  "mcpServers": {
    "dbeaver-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["dbeaver-mcp"],
      "env": {}
    }
  }
}

Direct Connect Mode

When DBeaver is not installed, use database-mcp to connect directly:

npx database-mcp --host <host> --username <user> --password <pass> --database <db> --name <connection-name> [--driver mysql8] [--port <port>]

Supported drivers: mysql8, mysql5, mariadb, postgres, postgresql, postgres-jdbc, oracle, redis

Example MCP server configuration for direct mode:

{
  "mcpServers": {
    "database-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "database-mcp",
        "--host", "192.168.1.100",
        "--port", "3306",
        "--username", "admin",
        "--password", "secret",
        "--database", "mydb",
        "--driver", "mysql8",
        "--name", "my-mysql"
      ]
    }
  }
}

Available Tools

Connection Management

Query Execution

Schema Inspection

Performance & Monitoring

Permissions

Control which SQL operations are allowed globally or per connection via ~/.dbeaver-mcp/settings.json:

{
  "permissions": {
    "global": {
      "allowed_operations": ["SELECT", "SHOW", "EXPLAIN", "DESCRIBE"],
      "blocked_operations": ["DROP", "TRUNCATE"]
    },
    "connections": {
      "production": {
        "allowed_operations": ["SELECT", "SHOW", "EXPLAIN", "DESCRIBE"]
      },
      "staging": {
        "allowed_operations": ["SELECT", "INSERT", "UPDATE", "DELETE", "SHOW", "EXPLAIN", "DESCRIBE", "CREATE", "ALTER"]
      }
    }
  }
}

How permission resolution works:

1. Is there a specific entry for this connection in connections? → Use those permissions (total override)
2. No specific entry? → Use global permissions
3. No settings.json or no permissions key? → Everything is allowed (backward-compatible)

Whitelist vs blacklist:

• allowed_operations — only these operations are permitted (whitelist)
• blocked_operations — these operations are always blocked, even if not whitelisted

Recognized operations: SELECT, SHOW, EXPLAIN, DESCRIBE, INSERT, UPDATE, DELETE, CREATE, ALTER, DROP, TRUNCATE, GRANT, REVOKE, FLUSH, OPTIMIZE, REPAIR, USE, SET

DBeaver Workspace Paths

The server auto-detects your DBeaver workspace:

Additional paths are checked for alternative installations (Homebrew, Snap, etc.).

Testing Without Claude

# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | node ~/.skills/dbeaver-mcp/dist/index.js

Project Structure

dbeaver-mcp/
├── src/
│   ├── index.ts            # MCP server entry point (stdio transport)
│   ├── cli-auto.ts         # CLI entry: auto mode (reads from DBeaver)
│   ├── cli-direct.ts        # CLI entry: direct connect mode (CLI args, no DBeaver required)
│   ├── dbeaver.ts          # Core: read/write DBeaver configs, AES-128-CBC crypto
│   ├── permissions.ts      # Permission system (global + per-connection)
│   ├── mysql.ts            # MySQL connection and query execution (mysql2)
│   ├── postgres.ts         # PostgreSQL connection and query execution (pg)
│   ├── oracle.ts           # Oracle connection and query execution (oracledb)
│   ├── commands/
│   │   └── install.ts      # Built-in installer (verify DBeaver, create config, register in Claude)
│   └── tools/
│       ├── connections.ts  # Tools: list, get, add, edit, remove, test connection
│       ├── queries.ts      # Tools: run_query, run_write
│       └── schema.ts       # Tools: list_tables, describe_table, explain, processlist, slow queries
├── dist/                   # Compiled JS (generated by tsc)
├── references/
│   ├── dbeaver/            # DBeaver internals (credentials, datasources, workspace)
│   ├── mysql/              # MySQL reference guides
│   ├── postgres/           # PostgreSQL reference guides
│   └── oracle/             # Oracle reference guides
├── package.json            # NPX-ready with bin field
├── tsconfig.json           # TypeScript config (ES2022, strict)
├── settings.example.json   # Example permissions config
├── SKILL.md                # AI agent skill definition
├── CLAUDE.md               # Project instructions for Claude Code
└── .gitignore              # Blocks credentials and sensitive files

Requirements

• Node.js 18+
• DBeaver installed with at least one saved connection
• MySQL, PostgreSQL, or Oracle database accessible from your machine

Dependencies

License

MIT