How do I use databricks-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@databricks-mcp Show me the schema and recent history for the sales_data table" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

databricks-mcp

by ChrisChoTW

Overview Schema Source Related Servers Discussions Admin

Python

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

Related MCP server: secoda-analysis-mcp

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!

Available Tools

25 tools

databricks_queryA

Execute Databricks SQL query (supports SELECT, SHOW, DESCRIBE, CREATE, ALTER). INSERT, UPDATE, DELETE, DROP and other destructive operations are blocked.

Args: sql_query: SQL query statement (preferred parameter) sql: SQL query statement (fallback for backward compatibility)

Returns: Query results as list of dicts

Inputs: sql_query, sql. Returns: result

get_cluster_eventsB

Get cluster event history (start, terminate, resize, errors, etc.)

Args: cluster_id: Cluster ID limit: Max number of records to return

Returns: Event list (time in local timezone)

Inputs: cluster_id (required), limit. Returns: result

get_cluster_metricsB

Get cluster CPU/Memory/Network/Disk metrics

Data source: system.compute.node_timeline (one record per minute)

Args: cluster_id: Cluster ID start_time: Start time (ISO format), defaults to last 1 hour end_time: End time (ISO format), defaults to now limit: Max number of records to return, default 60 (1 hour)

Returns: Metrics time series and summary statistics

Inputs: cluster_id (required), start_time, end_time, limit. Returns: object

get_grantsB

View object permissions (SHOW GRANTS)

Args: securable_type: Object type (TABLE, SCHEMA, CATALOG, VOLUME, etc.) full_name: Full object name (catalog.schema.table format)

Inputs: securable_type (required), full_name (required). Returns: result

get_jobD

Get job details

Inputs: job_id (required). Returns: object

get_job_runD

Get run details

Inputs: run_id (required). Returns: object

get_pipelineD

Get pipeline status

Inputs: pipeline_id (required). Returns: object

get_run_task_metricsB

Get job run task execution time details

Args: run_id: Job Run ID

Returns: Task setup/execute/cleanup times (time in local timezone)

Inputs: run_id (required). Returns: object

get_table_detailC

View Delta table details (DESCRIBE DETAIL)

Inputs: catalog (required), schema (required), table (required). Returns: result

get_table_historyC

View Delta table change history (DESCRIBE HISTORY)

Inputs: catalog (required), schema (required), table (required), limit. Returns: result

get_table_lineageA

Get table lineage (upstream/downstream tables and related notebooks/jobs)

Args: catalog: Catalog name schema: Schema name table: Table name include_notebooks: Include notebook/job associations (slower) limit: Max rows to return (default 50)

Returns: Dict with upstream, downstream tables and optionally notebook/job info

Inputs: catalog (required), schema (required), table (required), include_notebooks, +1 more. Returns: object

get_table_schemaC

Get table structure (DESCRIBE EXTENDED)

Inputs: catalog_name (required), schema_name (required), table_name (required). Returns: result

list_catalogsB

List all catalogs

Inputs: no named parameters. Returns: result

list_clustersC

List Clusters

Inputs: limit. Returns: result

list_job_runsC

List job run history

Inputs: job_id (required), limit. Returns: result

list_jobsD

List Jobs

Inputs: limit, expand_tasks. Returns: result

list_pipelinesB

List Delta Live Tables Pipelines

Inputs: limit. Returns: result

list_pipeline_updatesC

List pipeline update history

Inputs: pipeline_id (required), limit. Returns: result

list_query_historyB

List SQL query history

Args: warehouse_id: (Optional) Filter by specific warehouse user_id: (Optional) Filter by specific user start_time: (Optional) Start time in local format "YYYY-MM-DD HH:MM:SS" end_time: (Optional) End time in local format "YYYY-MM-DD HH:MM:SS" limit: Number of results to return

Inputs: warehouse_id, user_id, start_time, end_time, +1 more. Returns: result

list_schemasC

List schemas in the specified catalog

Inputs: catalog_name (required). Returns: result

list_tablesC

List tables in the specified schema

Inputs: catalog_name (required), schema_name (required). Returns: result

list_volumesC

List Unity Catalog Volumes

Inputs: catalog (required), schema (required). Returns: result

list_warehousesB

List SQL Warehouses

Inputs: no named parameters. Returns: result

list_workspaceC

List Workspace directory contents

Inputs: path. Returns: result

search_tablesC

Search tables by name (using information_schema)

Inputs: keyword (required), catalog. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.8/5.0

Scored 2026-04-17 19:36 across 25 tools

Disambiguation4/5

Most tools have distinct purposes targeting specific Databricks resources (clusters, jobs, tables, etc.), but some overlap exists. For example, get_table_detail, get_table_schema, and get_table_history all focus on table metadata with potentially unclear boundaries for an agent. However, descriptions help differentiate them by specifying different aspects (detail vs. schema vs. history).

Naming Consistency5/5

Tool names follow a highly consistent verb_noun pattern throughout, with clear and predictable conventions. All tools use either 'get_', 'list_', or 'search_' prefixes followed by the resource name (e.g., get_cluster_events, list_jobs, search_tables), making them easily readable and systematic.

Tool Count3/5

With 25 tools, the count is borderline high for a single server, potentially overwhelming for an agent. While Databricks is a complex platform, this many tools might indicate fragmentation or redundancy, such as multiple table-related tools that could be consolidated. It feels heavy but not extreme.

Completeness4/5

The tool set provides broad coverage for monitoring and querying Databricks resources, including clusters, jobs, tables, pipelines, and more. Minor gaps exist, such as lack of create/update/delete operations for many resources (e.g., no create_cluster or delete_job), but agents can work around this with the provided query tool for some operations. Core read and list functionalities are well-covered.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Dataassist-IO
io.github.DataAssistIO
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Search Databases
2
https://app.dataassist.io/mcp
DatabricksB
io.github.mcp-dir
Your Databricks Lakehouse in natural language: run SQL on your SQL warehouses, track long-running qu
Data Platforms Databases
171
https://api.mcp.ai/p_databricks
Contextflo
com.contextflo
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Databases Security
1
https://mcp.contextflo.com/mcp
AI2SQL
io.ai2sql
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Databases Developer Tools
1
https://builder.ai2sql.io/api/chatgpt-mcp

Related MCP Servers

bricks-use
Databases Cloud Platforms
aymenfurter
A
license
Not graded
quality
D
maintenance
MCP server for executing Databricks SQL queries and comparing table data, supporting CLI and VS Code integration.
Updated a year ago (2025-07-09 17:50 UTC)
1
MIT
secoda-analysis-mcp
Search Knowledge & Memory Databases
mbrummerstedt
A
license
A
quality
D
maintenance
A read-only MCP server for exploring and analyzing a Secoda data catalog, enabling AI chat, semantic search, glossary browsing, and data lineage tracing.
Updated 7 months ago (2026-04-09 13:25 UTC)
12
Apache 2.0
sqldb-mcp-server
Databases Developer Tools
akrym1582
A
license
A
quality
B
maintenance
A read-only MCP server that exposes SQL database access to LLMs, supporting multiple database types, compact columnar results, pagination, and file export.
Updated 2 months ago (2026-09-25 09:54 UTC)
7
20 npm
MIT
dagsmith
Databases Developer Tools
tmcwilliam707
A
license
Not graded
quality
D
maintenance
MCP server providing read-only Snowflake metadata tools (schemas, tables, queries, lineage) for agentic data pipeline generation, enabling natural-language-to-pipeline workflows with dbt, Airflow, and Great Expectations.
Updated 3 months ago (2026-08-04 15:27 UTC)
1
MIT

Appeared in Searches

DataNexus MCP Inspector - Resources Tab

databricks-mcp

Features

Installation

Prerequisites

Setup

Configuration

Usage

With Claude Code

Standalone

Available Tools

SQL & Metadata

Delta Lake

Jobs & Pipelines

Compute & Monitoring

Project Structure

Security

License

Contributing

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

bricks-use

secoda-analysis-mcp

sqldb-mcp-server

dagsmith

Appeared in Searches