# MCP Server for Databend

[![PyPI - Version](https://img.shields.io/pypi/v/mcp-databend)](https://pypi.org/project/mcp-databend)

Connect AI agents to your Databend database safely. Session sandbox keeps production read-only while agents experiment. Works with Codex, Cursor, Claude Code, Gemini CLI, and any MCP-compatible client. Learn more at [databend.com/mcp](https://www.databend.com/mcp/).

## Usage

1. Get your Databend DSN.
   Format: `databend://user:password@host:port/database?warehouse=your_warehouse`
   Get it from [Databend Cloud](https://app.databend.com) or the [docs](https://docs.databend.com/developer/drivers/#connection-string-dsn).
2. Session sandbox safety: writes only to `mcp_sandbox_{session_id}_*`; production stays read-only.
   Use `get_session_sandbox_prefix` to retrieve the live prefix.
3. Configure your MCP client.

**Standard config** works in most tools:

```js
{
  "mcpServers": {
    "databend": {
      "command": "uv",
      "args": ["tool", "run", "--from", "mcp-databend@latest", "mcp-databend"],
      "env": {
        "DATABEND_DSN": "databend://user:password@host:port/database?warehouse=your_warehouse"
      }
    }
  }
}
```

<details>
<summary>Codex</summary>

Use the Codex CLI to add the Databend MCP server:

```bash
codex mcp add databend \
  --env DATABEND_DSN='databend://user:password@host:port/database?warehouse=your_warehouse' \
  -- uv tool run --from mcp-databend@latest mcp-databend
```

</details>

<details>
<summary>Claude Code</summary>

Use the Claude Code CLI to add the Databend MCP server:

```bash
claude mcp add databend \
  --env DATABEND_DSN='databend://user:password@host:port/database?warehouse=your_warehouse' \
  -- uv tool run --from mcp-databend@latest mcp-databend
```

</details>

<details>
<summary>Cursor</summary>

#### Click the button to install:

[<img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Install in Cursor">](https://cursor.com/en/install-mcp?name=Databend&config=eyJjb21tYW5kIjoidXYgdG9vbCBydW4gLS1mcm9tIG1jcC1kYXRhYmVuZEBsYXRlc3QgbWNwLWRhdGFiZW5kIn0%3D)

Then open `Cursor Settings` -> `MCP`, select `Databend`, click `Edit`, and add `DATABEND_DSN` to the env section. Cursor keeps the command as a single string:

```json
{
  "mcpServers": {
    "Databend": {
      "command": "uv tool run --from mcp-databend@latest mcp-databend",
      "env": {
        "DATABEND_DSN": "databend://user:password@host:port/database?warehouse=your_warehouse"
      },
      "args": []
    }
  }
}
```

#### Or install manually:

Go to `Cursor Settings` -> `MCP` -> `Add new MCP Server`. Paste command `uv tool run --from mcp-databend@latest mcp-databend`, then click `Edit` and add `DATABEND_DSN` in env.

</details>

<details>
<summary>Gemini CLI</summary>

Add the standard config above to your Gemini CLI `settings.json`.

</details>

## Safety Guarantees

| Scope | Rules |
|-------|-------|
| Read access | `SELECT/SHOW/DESCRIBE/EXPLAIN/LIST` on any object. |
| Write access | Only objects prefixed with `mcp_sandbox_{session_id}_*`. |
| Sandbox objects | `CATALOG`, `DATABASE`, `TABLE`, `VIEW`, `STAGE`, `FUNCTION`, `USER`, `ROLE`, `TASK`, `PIPE`, `STREAM`, `CONNECTION`, `WAREHOUSE`, `SEQUENCE`, `PROCEDURE`, `DICTIONARY`, `TAG`, `FILE FORMAT`, `NETWORK POLICY`, `PASSWORD POLICY`, `MASKING POLICY`, `ROW ACCESS POLICY`, `NOTIFICATION INTEGRATION`, `WORKLOAD GROUP`, `DYNAMIC TABLE`, `INDEX` (AGGREGATING/INVERTED/NGRAM/VECTOR). |
| Write rules | `CREATE/CREATE OR REPLACE/DROP/ALTER` on sandbox objects; DML only on sandbox tables (`INSERT/UPDATE/DELETE/TRUNCATE/COPY/MERGE/REPLACE`); `GRANT/REVOKE` only on sandbox objects/principals; `ALTER ... SET|UNSET TAG` requires sandbox tag + target; `CREATE TASK|PIPE|DYNAMIC TABLE|INDEX ... AS` and `CREATE STREAM ... ON TABLE` only sandbox refs; `REMOVE @stage` only sandbox stages. |

## Available Tools

| Tool | Description |
|------|-------------|
| `execute_sql` | Execute SQL with sandbox validation |
| `execute_multi_sql` | Execute multiple SQL statements |
| `show_databases` | List all databases |
| `show_tables` | List tables in database |
| `describe_table` | Get table schema |
| `get_session_sandbox_prefix` | Get current session prefix |
| `list_session_sandbox_databases` | List sandbox databases |
| `create_session_sandbox_database` | Create sandbox database |
| `show_stages` / `list_stage_files` / `create_stage` | Stage management |
| `show_connections` | List connections |

## Configuration

| Variable | Default | Description |
|----------|---------|-------------|
| `DATABEND_DSN` | - | Connection string |
| `LOCAL_MODE` | `false` | Use embedded Databend |
| `DATABEND_QUERY_TIMEOUT` | `300` | Query timeout (seconds) |
| `DATABEND_MCP_SAFE_MODE` | `true` | Enable sandbox validation. Set to `false` to allow all SQL permitted by the Databend user. |
| `DATABEND_MCP_SERVER_TRANSPORT` | `stdio` | Transport: `stdio`, `http`, `sse` |
| `DATABEND_MCP_BIND_HOST` | `127.0.0.1` | Bind host for HTTP/SSE |
| `DATABEND_MCP_BIND_PORT` | `8001` | Bind port for HTTP/SSE |

Local mode stores data in `.databend/`.

## Development

```bash
git clone https://github.com/databendlabs/mcp-databend
cd mcp-databend
uv sync

# Run locally
uv run python -m mcp_databend.main

# Debug
npx @modelcontextprotocol/inspector uv run python -m mcp_databend.main

# Test
uv run pytest
```