Databricks Utils MCP Server

An MCP (Model Context Protocol) server for Databricks development and operations. Compatible with any MCP client: Claude Code, Claude Desktop, Cursor, and others.

Covers ten areas:

• Unity Catalog -- browse catalogs, schemas, tables, volumes, and functions; describe table schemas; sample table data
• SQL -- execute SQL statements; manage SQL warehouses (list, start, stop)
• Query History -- list recent queries; get full query details
• Jobs -- list, inspect, trigger, cancel, and repair job runs
• Clusters -- list (with filtering and paging), inspect, start, and terminate clusters
• Pipelines -- list, inspect, start, and stop Delta Live Tables pipelines
• Workspace -- browse workspace directories; export notebooks
• Files -- list and read files from DBFS and Unity Catalog Volumes
• Secrets -- list secret scopes and key names (values are never returned)
• Permissions -- get Unity Catalog grants and workspace object ACLs

Authentication uses the Databricks SDK's standard credential chain, which auto-discovers credentials from ~/.databrickscfg profiles, environment variables, or Azure CLI. Raw tokens are never passed as tool parameters. See Authentication below.

Requirements

• uv
• A Databricks workspace with a personal access token, OAuth config, or Azure CLI session

Installation

macOS

brew install uv

Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

winget install --id=astral-sh.uv

Configuration

Claude Code users:

claude mcp add --scope user databricks-utils -- uvx databricks-utils-mcp

For other MCP clients, add the following to your server configuration:

{
  "mcpServers": {
    "databricks-utils": {
      "command": "uvx",
      "args": ["databricks-utils-mcp"]
    }
  }
}

Restart your MCP client after adding the server.

Installing from source

git clone https://github.com/BrianDeacon/databricks-utils-mcp
cd databricks-utils-mcp
uv sync

Then configure with the cloned path:

{
  "mcpServers": {
    "databricks-utils": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/databricks-utils-mcp", "databricks-utils-mcp"]
    }
  }
}

Authentication

All tools use the Databricks SDK's unified authentication. By default, the SDK checks (in order): environment variables, ~/.databrickscfg default profile, Azure CLI, and other standard credential sources.

Every tool accepts three optional parameters to override the default:

Example ~/.databrickscfg

[DEFAULT]
host  = https://adb-1234567890.0.azuredatabricks.net/
token = dapi...

[staging]
host      = https://adb-0987654321.0.azuredatabricks.net/
auth_type = databricks-cli

With this config, tools use the DEFAULT profile automatically. Pass profile="staging" to target the staging workspace instead.

Unity Catalog Tools

catalog_list_catalogs

List all Unity Catalog catalogs accessible to the current user. Returns a sorted JSON array of catalog names.

catalog_list_schemas

catalog_list_tables

catalog_describe_table

Returns columns (name, type, comment), table type, storage location, properties, and timestamps.

catalog_get_table_sample

Executes SELECT * LIMIT against a table using a SQL warehouse. Returns a JSON array of row objects.

catalog_list_volumes

catalog_list_volume_files

catalog_list_functions

SQL Tools

sql_execute

Execute a SQL statement against a Databricks SQL warehouse. Returns a JSON array of row objects for queries, or a status message for DDL/DML.

sql_list_warehouses

List all SQL warehouses. Returns a JSON array with id, name, state, cluster_size, and auto_stop_mins.

sql_get_warehouse

sql_start_warehouse

Start a stopped SQL warehouse. Does not wait for it to finish starting.

sql_stop_warehouse

Stop a running SQL warehouse.

Query History Tools

query_history_list

List recent SQL queries. Returns query ID, statement (truncated), status, duration, rows produced, user, and warehouse.

query_history_get

Get full details for a specific query including the complete statement text, metrics, and error message if failed.

Jobs Tools

jobs_list

jobs_get

Returns tasks, schedule, clusters, parameters, tags, and notifications.

jobs_list_runs

jobs_get_run

Returns per-task states, start/end times, cluster info, error messages, and attempt number.

jobs_get_run_output

Returns notebook output, error trace, and logs depending on task type. Only works for single-task runs.

jobs_run

Trigger a job run. Does not wait for completion. Returns the run_id for tracking.

jobs_cancel_run

jobs_repair_run

Re-run failed tasks in a multi-task job run.

Cluster Tools

clusters_list

Results are paged (default 20 per page). The response includes next_page_token and prev_page_token when more pages are available.

clusters_get

clusters_get_events

Returns recent events including termination reasons.

clusters_start

Start a terminated cluster. Does not wait for it to finish starting.

clusters_terminate

Terminate a running cluster. This stops the cluster but does not delete it.

Pipeline Tools

pipelines_list

pipelines_get

Returns target catalog/schema, clusters, libraries, and notifications.

pipelines_list_events

Returns events including update progress, errors, and data quality metrics.

pipelines_start

Start a pipeline update. Returns the update_id for tracking.

pipelines_stop

Workspace Tools

workspace_list

List objects in a workspace directory. Returns path, object_type (NOTEBOOK, DIRECTORY, FILE, REPO), and language (for notebooks).

workspace_export_notebook

For SOURCE format, returns the notebook content as text. For other formats, returns base64-encoded content.

Files Tools

files_list

List files in a DBFS or Volumes path.

files_read

Read a file from Volumes or DBFS. Returns text content for text files, or a size summary for binary files.

Secrets Tools

secrets_list_scopes

List all secret scopes in the workspace. Returns a sorted JSON array of scope names.

secrets_list_keys

List secret key names in a scope. Values are never returned.

Permissions Tools

permissions_get_grants

Get Unity Catalog grants on a securable object. Returns principal and privilege list.

permissions_get_object_permissions

Get access control list for a workspace object. Returns principal and permission levels.

Security

• Authentication uses the Databricks SDK's standard credential chain. Tokens are never passed directly as tool parameters.
• The token_env_var parameter accepts only the name of an environment variable, not the token value itself. The value is read locally and never leaves the machine.
• SQL execution enforces a max_rows cap of 10,000. File reads enforce a max_bytes cap of 10 MB.
• Secret values are never exposed. The secrets_list_keys tool returns key names only.