Databricks MCP Server

A production-grade Model Context Protocol server for Databricks. Exposes the Databricks REST API as MCP tools over stdio (local) and Streamable HTTP (hosted/multi-user).

• TypeScript (ESM, Node 20+), REST-only over the Databricks API
• Three auth options: PAT, OAuth M2M (service principal), and HTTP per-user token passthrough
• Per-tool RBAC, destructive-op guard, secret redaction, structured logging, retry + per-host circuit breaker
• Covers the full developer surface plus the databrickslabs/mcp specialties (Unity Catalog, Vector Search, Genie)

Status: All phases complete — 107 tools across 13 domains, plus 4 resources and 4 prompts:

• clusters (12) · jobs (13) · warehouses (7) · sql (3, statement execution)
• workspace (6, notebooks/folders) · dbfs (6) · repos (5)
• catalog (22, Unity Catalog: catalogs/schemas/tables/volumes/functions/models/grants)
• secrets (6) · pipelines (8, Delta Live Tables) · serving (5, model serving)
• ml (10, Vector Search + Genie) · identity (5, SCIM)
• Resources: databricks://clusters, …/jobs, …/catalogs, databricks://catalog/{c}/schema/{s}/tables
• Prompts: explore-data, run-and-monitor-job, diagnose-failed-run, ask-genie

1. Prerequisites

• Node.js ≥ 20
• A Databricks workspace URL and either a PAT or a service principal (client ID + secret with OAuth)

2. Install & configure

cd "E:\MCP Servers\databricks-mcp-server"
npm install
cp .env.example .env   # PowerShell: Copy-Item .env.example .env

Minimum for local use with a PAT:

DATABRICKS_HOST=https://adb-1234567890.12.azuredatabricks.net
AUTH_MODE=pat
DATABRICKS_TOKEN=dapi...
DATABRICKS_DEFAULT_WAREHOUSE_ID=   # optional, for databricks_execute_sql
DATABRICKS_DEFAULT_CATALOG=        # optional

Auth modes

| AUTH_MODE | Needs | Notes | |---|---|---| | pat | DATABRICKS_TOKEN | Personal access token. Simplest. | | oauth | DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET | Service principal (M2M). Token minted at {host}/oidc/v1/token. Deployment path. |

On the HTTP transport, if a caller sends Authorization: Bearer <their-databricks-token> and ALLOW_TOKEN_PASSTHROUGH=true, that token is used for the request (per-user multi-tenant) — no shared identity needed.

3. Build & run

npm run build && npm start            # stdio (default)
node dist/index.js --transport http   # Streamable HTTP on PORT (default 3200)

4. Connect a client (npx)

{
  "mcpServers": {
    "databricks": {
      "command": "npx",
      "args": ["-y", "databricks-mcp-server"],
      "env": {
        "DATABRICKS_HOST": "https://adb-1234567890.12.azuredatabricks.net",
        "AUTH_MODE": "pat",
        "DATABRICKS_TOKEN": "dapi..."
      }
    }
  }
}

Verify with the databricks_current_user tool (confirms auth + connectivity).

5. Scripts

| Script | Purpose | |---|---| | npm run build | Compile TypeScript → dist/ | | npm start / start:http | Run compiled server (stdio / HTTP) | | npm run dev / dev:http | Watch-mode dev (tsx) | | npm run typecheck · lint · test · ci | Quality gates |

6. Architecture

transport (stdio | http)
  → server (McpServer + registry)
    → dispatch (RBAC · destructive guard · audit · error envelope)
      → domain tools (Zod schemas)
        → domain services
          → DatabricksClient (REST + retry + circuit breaker)
            → credential (PAT | OAuth M2M | HTTP passthrough)

Each Databricks area is a self-contained module under src/domains/<area>/ exporting a DomainModule. To add an area, create the module and append it to domains in src/server.ts.

Full walkthrough: see docs/END_TO_END_FLOW.md for how a request travels through every layer.