# dbeaver-mcp-server

[中文文档](README.zh.md)

MCP server that reads DBeaver database configurations and provides SQL execution via existing JDBC drivers — no extra driver downloads needed.

## Features

- **Auto-discover** DBeaver workspaces and projects (macOS / Linux / Windows)
- **List connections** from DBeaver's `data-sources.json`
- **Execute read-only SQL** via DBeaver's existing JDBC drivers (JayDeBeApi + JPype)
- **Auto-decrypt** DBeaver's encrypted credentials
- **Multi-driver support** — all JDBC drivers installed in DBeaver are loaded at once

## Tools

| Tool | Description |
|---|---|
| `list_workspaces` | List all discovered DBeaver workspaces and projects |
| `list_connections` | List database connections, optionally filtered by workspace |
| `execute_sql` | Execute a read-only SQL query (only SELECT / SHOW / DESCRIBE / EXPLAIN / WITH) |

## Requirements

- Python >= 3.13
- [uv](https://docs.astral.sh/uv/) (Python package manager)
- Java Runtime (for JPype/JDBC)
- [DBeaver](https://dbeaver.io/) 26.x (Community Edition)

## Installation

```bash
git clone <repo-url> dbeaver-mcp-server
cd dbeaver-mcp-server
uv sync
```

## Usage

### Standalone

```bash
cd /path/to/dbeaver-mcp-server
source .venv/bin/activate
mcp dev src/server.py
```

### With OpenCode

Add to `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "dbeaver": {
      "type": "local",
      "command": [
        "/path/to/dbeaver-mcp-server/.venv/bin/python",
        "-m",
        "src.server"
      ],
      "enabled": true
    }
  }
}
```

### Environment Variables

| Variable | Description | Default |
|---|---|---|
| `DBEAVER_WORKSPACE_PATH` | Override workspace path | Auto-discovered |
| `DBEAVER_DRIVERS_XML_PATH` | Override drivers.xml path | Auto-discovered |
| `DBEAVER_ENCRYPTION_KEY` | Override credential encryption key (hex) | Default |

## Security

- Only **read-only** SQL is allowed: `SELECT`, `SHOW`, `DESCRIBE`, `EXPLAIN`, `WITH`
- `INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER`, `CREATE`, `TRUNCATE` are **blocked**
- Passwords are decrypted in-memory only, never written to disk

## How It Works

1. Discovers DBeaver workspace via default paths or `DBEAVER_WORKSPACE_PATH`
2. Reads `data-sources.json` for connection configurations
3. Reads `drivers.xml` and scans JDBC jars for driver class names
4. Decrypts `credentials-config.json` using DBeaver's AES-128-CBC key
5. Starts a JVM with all JDBC jars and executes queries via JayDeBeApi