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!