databricks-mcp

Read this in other languages: 正體中文

A read-only MCP (Model Context Protocol) server for Databricks, enabling Claude to query Databricks SQL, browse metadata, and monitor jobs/pipelines.

Features

SQL Queries: Execute SELECT, SHOW, DESCRIBE queries (write operations blocked)
Metadata Browsing: List catalogs, schemas, tables, and search tables
Delta Lake: View table history, details, and grants
Jobs & Pipelines: List and monitor Databricks Jobs and DLT Pipelines
Query History: Browse SQL query history with filters
Cluster Metrics: Monitor CPU, memory, network usage from system tables

Installation

Prerequisites

Python 3.13+
uv package manager
Databricks workspace with SQL Warehouse

Setup

# Clone the repository
git clone https://github.com/ChrisChoTW/databricks-mcp.git
cd databricks-mcp

# Install dependencies
uv sync

# Create .env file
cp .env.example .env

Configuration

Edit .env with your Databricks credentials:

DATABRICKS_SERVER_HOSTNAME=your-workspace.cloud.databricks.com
DATABRICKS_HTTP_PATH=/sql/1.0/warehouses/your-warehouse-id
DATABRICKS_TOKEN=your-personal-access-token

Usage

With Claude Code

Add to your Claude Code MCP configuration (~/.claude.json):

{
  "mcpServers": {
    "databricks-sql": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/databricks-mcp",
        "run",
        "python",
        "server.py"
      ],
      "env": {
        "DATABRICKS_SERVER_HOSTNAME": "your-workspace.cloud.databricks.com",
        "DATABRICKS_HTTP_PATH": "/sql/1.0/warehouses/your-warehouse-id",
        "DATABRICKS_TOKEN": "your-token"
      }
    }
  }
}

Standalone

uv run python server.py

Available Tools

SQL & Metadata

| Tool | Description | |------|-------------| | databricks_query | Execute SQL queries (read-only) | | list_catalogs | List all catalogs | | list_schemas | List schemas in a catalog | | list_tables | List tables in a schema | | get_table_schema | Get table structure (DESCRIBE EXTENDED) | | search_tables | Search tables by name |

Delta Lake

| Tool | Description | |------|-------------| | get_table_history | View Delta table change history | | get_table_detail | View Delta table details | | get_grants | View object permissions | | list_volumes | List Unity Catalog volumes |

Jobs & Pipelines

| Tool | Description | |------|-------------| | list_jobs | List Databricks Jobs | | get_job | Get job details | | list_job_runs | List job run history | | get_job_run | Get run details | | list_pipelines | List DLT Pipelines | | get_pipeline | Get pipeline status |

Compute & Monitoring

| Tool | Description | |------|-------------| | list_query_history | List SQL query history | | list_warehouses | List SQL Warehouses | | list_clusters | List clusters | | get_cluster_metrics | Get cluster CPU/memory metrics | | get_cluster_events | Get cluster events |

Project Structure

databricks-mcp/
├── server.py         # Entry point
├── core.py           # Shared connections and MCP instance
└── tools/
    ├── query.py      # SQL queries and metadata
    ├── delta.py      # Delta Lake and permissions
    ├── jobs.py       # Jobs management
    ├── pipelines.py  # DLT Pipelines
    ├── compute.py    # Clusters and query history
    └── metrics.py    # Cluster metrics

Security

This server is read-only by design:

❌ INSERT, UPDATE, DELETE, DROP, TRUNCATE, MERGE, COPY blocked
✅ SELECT, SHOW, DESCRIBE, CREATE VIEW allowed
Credentials are passed via environment variables (never hardcoded)

License

MIT

Contributing

Issues and pull requests are welcome!

MCP Servers