# databricks-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that
exposes the [Databricks REST APIs](https://docs.databricks.com/api) as MCP
tools so an LLM agent can manage and query a Databricks workspace.

The server speaks MCP over **stdio** (for Claude Desktop / Claude Code /
Cursor / IDE hosts) and supports a single `--transport streamable-http` mode
for remote deployments (Databricks Apps, container, etc.).

**Safe by default.** Out of the box only `list` and `create` tools are
exposed — roughly 110 of the 303 available. Mutating, destructive, and
single-record-read tools are hidden until you opt in via env vars or CLI
flags. See [Permissions](#permissions-safe-by-default) below.

## Features

303 tools across these Databricks domains. **Default visibility**
indicates whether the tools are exposed in safe-by-default mode; everything
else is opt-in.

| Domain | Tools | Default |
| --- | --- | --- |
| **Workspace** | list / get / create / delete / export / import notebooks; list / get / mkdir / delete workspace files and dirs | list, create only |
| **Clusters** | list, get, create, start, terminate, restart, resize, edit, delete; cluster events; cluster policies; instance pools; node types; spark versions | list, create only |
| **Jobs** | list, get, create, run-now, list-runs, get-run, cancel-run, delete; full task types (notebook, spark_jar, python_wheel, dbt, sql, pipeline, run_job, condition, for_each) | list, create only |
| **SQL Warehouses** | list, get, create, start, stop, edit, delete | list, create only |
| **SQL Queries / Dashboards / Alerts / Data** | list / get / run SQL statements, dashboards (legacy + Lakeview), alerts | list, create only |
| **Unity Catalog** | catalogs, schemas, tables, columns, volumes, functions, grants, model versions | list, create only |
| **Delta Live Tables (Pipelines)** | list, get, create, start, stop, delete; pipeline updates | list, create only |
| **MLflow** | experiments, runs, models, registered models, model versions, webhooks | list, create only |
| **Model Serving** | serving endpoints (create, list, get, update, delete, query) | list, create only |
| **Vector Search** | endpoints (create, list, get, delete), indexes (create, list, get, delete, upsert, query, scan) | list, create only |
| **Databricks Apps** | list, get, create, update, delete | list, create only |
| **Repos (Git)** | list, get, create, update, delete; pull, push, commit | list, create only |
| **Secrets** | list, put, get, delete scopes and secrets | list, create only |
| **DBFS** | list, get, put, delete files | list, create only |
| **Tokens** | list, create, revoke | list, create only |
| **Permissions** | get / set / update / delete ACLs on jobs, clusters, pipelines, etc. | list, create only |
| **Identity / SCIM** | list users, groups, service principals | list, create only |
| **Delta Sharing** | list / create / update / delete shares, recipients, providers | list, create only |
| **Genie (AI/BI)** | list spaces, ask-question | list, create only |
| **Account APIs** | workspaces, metastores, storage, credentials, users, groups, service principals | list, create only |
| **Utilities** | workspace status, current user, whoami, auth_config | always exposed |

To expose everything (legacy behaviour), set
`DATABRICKS_MCP_ENABLE_VERBS=list,get,create,update,delete`.

## Install

```bash
# From source (this repo)
uv tool install .

# Or pipx / pip
pipx install .
# or
pip install .

# Or run directly with uvx
uvx --from . databricks-mcp
```

## Configure

The server needs three environment variables (or CLI flags):

| Variable | Required | Example |
| --- | --- | --- |
| `DATABRICKS_HOST` | yes | `https://dbc-1234567890.cloud.databricks.com` |
| `DATABRICKS_TOKEN` | one of PAT or OAuth must be set | `dapi...` (Personal Access Token) |
| `DATABRICKS_CLIENT_ID` + `DATABRICKS_CLIENT_SECRET` | OAuth M2M alternative to PAT | — |
| `DATABRICKS_ACCOUNT_ID` | only for account-level APIs | `1234567890` |

You can also pass them as CLI flags: `--host`, `--token`.

## Permissions (safe by default)

Each tool is classified into one of five verb categories. The default
policy exposes only `list` and `create`; the rest are hidden.

| Category | Default | Approx. tools | Examples |
| --- | --- | --- | --- |
| `list` | **ON** | ~50 | `clusters_list`, `uc_table_list`, `whoami`, `auth_config` |
| `create` | **ON** | ~30 | `clusters_create`, `uc_table_create`, `secrets_create_scope` |
| `get` | OFF | ~60 | `clusters_get`, `uc_table_get`, `secrets_get_secret` |
| `update` | OFF | ~100 | `clusters_edit`, `jobs_update`, `sql_statements_execute`, `permissions_set` |
| `delete` | OFF | ~60 | `clusters_delete`, `jobs_delete`, `tokens_revoke`, `permissions_delete` |

### Three knobs

In increasing precedence:

| Knob | Env var | CLI flag |
| --- | --- | --- |
| Verb categories ON by default | `DATABRICKS_MCP_ENABLE_VERBS=list,create,get` | `--enable-verbs list,create,get` |
| Per-tool allow (always shown) | `DATABRICKS_MCP_ENABLE_TOOLS=jobs_run_now,clusters_edit` | `--enable-tool jobs_run_now` (repeatable) |
| Per-tool deny (always hidden) | `DATABRICKS_MCP_DISABLE_TOOLS=workspace_delete,dbfs_delete` | `--disable-tool workspace_delete` (repeatable) |

Resolution per tool: **deny wins over allow wins over verb category**.

### Examples

```bash
# Legacy behaviour — full surface exposed
DATABRICKS_MCP_ENABLE_VERBS=list,get,create,update,delete databricks-mcp

# Default + opt in to running jobs and editing clusters
DATABRICKS_MCP_ENABLE_TOOLS=jobs_run_now,clusters_edit databricks-mcp

# Default + hide notebook delete even though delete is OFF anyway
DATABRICKS_MCP_DISABLE_TOOLS=workspace_delete databricks-mcp

# Read-only audit agent
DATABRICKS_MCP_ENABLE_VERBS=list,get databricks-mcp

# CLI flag form (same as the first env-var example)
databricks-mcp --enable-verbs list,get,create,update,delete
```

Verify the active policy at runtime via the `auth_config` tool — it
returns a `policy` block with `enabled_verbs`, `allowed_tools`,
`denied_tools`, and `registered_tool_count`. Full reference:
[`docs/PERMISSIONS.md`](docs/PERMISSIONS.md).

## Use with Claude Desktop

Three ready-made profiles are in
[`examples/claude_desktop_config.json`](examples/claude_desktop_config.json):

- `databricks` — full surface (every verb enabled).
- `databricks-restricted` — default list+create plus destructive-tool denylist.
- `databricks-readonly` — list and get only.

Add the one you want to
`~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "databricks": {
      "command": "databricks-mcp",
      "env": {
        "DATABRICKS_HOST": "https://dbc-1234567890.cloud.databricks.com",
        "DATABRICKS_TOKEN": "dapi..."
      }
    }
  }
}
```

## Use with Claude Code

```bash
claude mcp add databricks \
  --transport stdio \
  --env DATABRICKS_HOST=https://dbc-1234567890.cloud.databricks.com \
  --env DATABRICKS_TOKEN=dapi... \
  -- databricks-mcp
```

To opt back into the full surface:

```bash
claude mcp add databricks \
  --transport stdio \
  --env DATABRICKS_HOST=https://dbc-1234567890.cloud.databricks.com \
  --env DATABRICKS_TOKEN=dapi... \
  --env DATABRICKS_MCP_ENABLE_VERBS=list,get,create,update,delete \
  -- databricks-mcp
```

## Run from source

```bash
# stdio (default)
uv run databricks-mcp

# streamable HTTP (for remote deployment / Databricks Apps)
uv run databricks-mcp --transport streamable-http --host 0.0.0.0 --port 8000
```

## Test with MCP Inspector

```bash
npx -y @modelcontextprotocol/inspector databricks-mcp
```

Set `DATABRICKS_HOST` and `DATABRICKS_TOKEN` in the Inspector's env form
and click Connect. Browse the tool list — by default you'll see only
list/create tools. To see everything, add
`DATABRICKS_MCP_ENABLE_VERBS=list,get,create,update,delete` to the env.
Try the `auth_config` tool first to verify your setup; it reports the
active policy as JSON.

## Documentation

- [`docs/PERMISSIONS.md`](docs/PERMISSIONS.md) — full permission reference,
  verb classification, common configurations.
- [`docs/AUTH.md`](docs/AUTH.md) — PAT vs OAuth M2M, on-behalf-of flow.
- [`docs/TOOLS.md`](docs/TOOLS.md) — every tool grouped by domain.
- [`docs/EXAMPLES.md`](docs/EXAMPLES.md) — sample invocations.
- [`docs/DEVELOPING.md`](docs/DEVELOPING.md) — how to add new tools.

## License

MIT.