Content
# MCP Server for 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
```
