Skip to main content

Databricks MCP Toolkit

PyPI Python CI License: AGPL-3.0

A Model Context Protocol server that lets Claude, Cursor, VS Code and other MCP clients work with a Databricks workspace. Through it, the assistant can browse Unity Catalog, run SQL, read and write volume files, manage clusters and jobs, export and import notebooks, and run code on a cluster.

  • Current Databricks APIs: Jobs 2.2, Clusters 2.1, Unity Catalog 2.1, the Files API for volumes, and SQL Statement Execution.
  • Any Databricks auth method: personal access tokens, OAuth (user or service principal), ~/.databrickscfg profiles and Azure CLI, all handled by the official databricks-sdk.
  • Safe to point at real workspaces: a read-only mode, per-toolset filtering, MCP tool annotations (read-only and destructive hints), no automatic retries of non-idempotent calls, and response size caps so a big result doesn't flood the model's context.

Quick start

You need Python 3.10+ and uv (or pipx/pip).

# try it without installing
uvx --from databricks-mcp-toolkit databricks-mcp list-tools

# or install it
pipx install databricks-mcp-toolkit      # or: pip install databricks-mcp-toolkit
databricks-mcp --version

Claude Desktop

Add this to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "databricks": {
      "command": "uvx",
      "args": ["--from", "databricks-mcp-toolkit", "databricks-mcp"],
      "env": {
        "DATABRICKS_HOST": "https://<your-workspace>.cloud.databricks.com",
        "DATABRICKS_TOKEN": "<personal-access-token>",
        "DATABRICKS_WAREHOUSE_ID": "<optional default SQL warehouse id>"
      }
    }
  }
}

Claude Code

claude mcp add databricks \
  -e DATABRICKS_HOST=https://<your-workspace>.cloud.databricks.com \
  -e DATABRICKS_TOKEN=<personal-access-token> \
  -- uvx --from databricks-mcp-toolkit databricks-mcp

Cursor / VS Code / other clients

Use the same command and env vars: uvx --from databricks-mcp-toolkit databricks-mcp. To serve over HTTP instead of stdio:

databricks-mcp run --transport streamable-http --host 127.0.0.1 --port 8000

Authentication

Auth is delegated to Databricks unified auth, so whatever works for the Databricks CLI works here:

Method Set
Personal access token DATABRICKS_HOST, DATABRICKS_TOKEN
OAuth service principal (M2M) DATABRICKS_HOST, DATABRICKS_CLIENT_ID, DATABRICKS_CLIENT_SECRET
OAuth user login (U2M) Run databricks auth login --host <url> once, then set DATABRICKS_CONFIG_PROFILE (or nothing for DEFAULT)
Config profile DATABRICKS_CONFIG_PROFILE=<name> from ~/.databrickscfg
Azure Azure CLI login or the ARM_* / DATABRICKS_AZURE_* variables

For anything shared or automated, use a service principal that has only the permissions the assistant needs. The server can do anything that identity can do.

Configuration

Variable Default Purpose
DATABRICKS_WAREHOUSE_ID none Default warehouse for execute_sql
DATABRICKS_MCP_READ_ONLY false Only expose tools that can't change anything (also --read-only)
DATABRICKS_MCP_TOOLSETS all Comma-separated subset: clusters,jobs,workspace,volumes,dbfs,sql,unity_catalog,commands (also --toolsets)
DATABRICKS_MCP_MAX_RESPONSE_CHARS 50000 Larger tool results are truncated with a note telling the model to narrow the request
DATABRICKS_MCP_HTTP_TIMEOUT 60 Per-request timeout, in seconds
DATABRICKS_MCP_MAX_RETRIES 3 Retries for 429s and for 5xx/timeouts on idempotent requests
DATABRICKS_MCP_LOG_LEVEL WARNING Logs go to stderr (stdout carries the MCP protocol)
DATABRICKS_MCP_TRANSPORT stdio stdio or streamable-http

Read-only mode

databricks-mcp run --read-only

This hides every tool that creates, changes or deletes something. That includes execute_sql and run_command, because arbitrary SQL or code can't be guaranteed read-only. What's left is browsing Unity Catalog, volumes, DBFS, the workspace, clusters, jobs, runs and warehouses. For read-only SQL, give a service principal SELECT-only grants and run without --read-only.

Tools

48 tools in 8 toolsets. Run databricks-mcp list-tools to see what your settings expose.

Clusters (clusters)

Tool Read-only What it does
list_clusters ✓ List pinned and active clusters, plus clusters terminated in the last 30 days.
get_cluster ✓ Get the full configuration and state of one cluster.
list_spark_versions ✓ List Databricks Runtime versions (spark_version keys) available for new clusters.
list_node_types ✓ List instance types (node_type_id values) available in this workspace.
create_cluster Create an all-purpose cluster. This starts billable compute.
start_cluster Start a terminated cluster.
restart_cluster Restart a running cluster. Running commands and notebook state are lost.
resize_cluster Resize a running cluster to a fixed worker count or an autoscale range.
terminate_cluster Terminate (stop) a cluster. Its config is kept and it can be started again.

Jobs (jobs)

Tool Read-only What it does
list_jobs ✓ List jobs (summary: id, name, creator, created time).
get_job ✓ Get a job's full settings (tasks, clusters, schedule, parameters).
list_job_runs ✓ List job runs, newest first.
get_run ✓ Get a run's details, including per-task state.
get_run_output ✓ Get a run's output: notebook exit value, logs, error and trace. For a multi-task run, returns each task's output.
wait_for_run ✓ Poll a run until it finishes or the timeout passes. Returns its final state.
run_job Trigger a run of an existing job. Returns run_id.
submit_run Submit a one-time run without creating a job. Returns run_id.
cancel_run Cancel an active run.

Workspace / notebooks (workspace)

Tool Read-only What it does
list_workspace ✓ List notebooks, files and folders in a workspace directory.
get_workspace_object ✓ Get metadata (type, language, ids) for a workspace path.
export_notebook ✓ Export a notebook's contents as text.
import_notebook Create or (with overwrite=true) replace a notebook. language is required for SOURCE.
create_workspace_directory Create a workspace folder, including missing parents.

Unity Catalog volumes (Files API) (volumes)

Tool Read-only What it does
list_volume_directory ✓ List files and folders in a Unity Catalog volume directory.
read_volume_file ✓ Read the start of a text file in a volume (up to max_bytes).
write_volume_file Write a text file to a volume. Fails if it exists unless overwrite=true.
delete_volume_file Delete a file from a volume.
create_volume_directory Create a directory in a volume, including missing parents.

DBFS (legacy, read-only) (dbfs)

Tool Read-only What it does
list_dbfs ✓ List a legacy DBFS path. Prefer volumes for new data.
read_dbfs_file ✓ Read the start of a text file on legacy DBFS.

SQL warehouses & queries (sql)

Tool Read-only What it does
list_sql_warehouses ✓ List SQL warehouses with their id, state and size.
get_sql_warehouse ✓ Get one SQL warehouse's full configuration and state.
start_sql_warehouse Start a stopped SQL warehouse.
stop_sql_warehouse Stop a SQL warehouse. Running queries on it are cancelled.
execute_sql Run a SQL statement on a SQL warehouse and return columns + rows. If it outlives timeout_seconds you get a statement_id to poll with get_sql_statement.
get_sql_statement ✓ Get the state and (if finished) results of a SQL statement.
cancel_sql_statement Cancel a running SQL statement.

Unity Catalog (unity_catalog)

Tool Read-only What it does
list_catalogs ✓ List Unity Catalog catalogs you can see.
list_schemas ✓ List schemas in a catalog.
list_tables ✓ List tables and views in a schema (names and types; use get_table for columns).
get_table ✓ Get a table's columns, types, comments, format and storage location.
list_volumes ✓ List Unity Catalog volumes in a schema.

Run code on a cluster (commands)

Tool Read-only What it does
run_command Run one snippet of code on a running cluster and return its result. Creates and destroys a throwaway context; use create_execution_context to keep state between calls.
create_execution_context Create a stateful execution context on a running cluster. Returns its id.
execute_command Run code in an existing context; variables persist between calls.
get_command_status ✓ Get a command's status and, when finished, its results.
cancel_command Cancel a running command.
destroy_execution_context Destroy an execution context and free its resources on the cluster.

Databricks API versions used

Area Endpoint
Jobs /api/2.2/jobs/* (current version; queues runs by default, pages tasks past 100)
Clusters /api/2.1/clusters/*
Unity Catalog /api/2.1/unity-catalog/*
Volumes Files API /api/2.0/fs/files, /api/2.0/fs/directories
SQL /api/2.0/sql/statements, /api/2.0/sql/warehouses
Workspace /api/2.0/workspace/*
Commands /api/1.2/contexts/*, /api/1.2/commands/* (still the current version)
DBFS /api/2.0/dbfs/* (legacy; read-only here)

Files API 3.0 is still in beta. It needs an admin preview toggle and a regional hostname, so the server stays on 2.0 for now.

Upgrading from 0.1.x

0.2.0 is a rewrite, and several things changed:

  • Install and command: install with pip install databricks-mcp-toolkit, then run databricks-mcp (or python -m databricks_mcp). Clone-and-pip install -e . is no longer needed, and the old start_mcp_server.sh and .ps1 scripts are gone.
  • Tool arguments: tools now take typed, named arguments. Before, every tool took one opaque params object.
  • Renamed tools:
    • list_notebooks → list_workspace
    • list_files → list_dbfs
    • submit_single_run → submit_run
    • wait_for_run_completion → wait_for_run
    • execute_command_simple → run_command
    • get_context_status was removed
  • MCP SDK: it now requires mcp>=2.3. The 0.1.x code imported FastMCP, which doesn't exist in MCP 2.x, so a fresh install of 0.1.x fails to start.

Development

git clone https://github.com/kshptl/Databricks-MCP-Server
cd Databricks-MCP-Server
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest              # unit tests; HTTP is mocked, so no workspace is needed
ruff check src tests && ruff format --check src tests

See CONTRIBUTING.md and ARCHITECTURE.md. Releases are covered in RELEASING.md.

License

Dual-licensed:

  • AGPL-3.0-only for open-source use. If you run a modified version as a network service, you must offer its source to the service's users.
  • Commercial license if the AGPL terms don't fit your use. Open an issue or contact the author through their GitHub profile.

This project is not affiliated with or endorsed by Databricks, Inc.

Metadata

Release files for databricks-mcp-toolkit 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for databricks-mcp-toolkit 0.2.0
File Size Uploaded Provenance Actions
databricks_mcp_toolkit-0.2.0.tar.gz 40.7 kB With provenance Details for databricks_mcp_toolkit-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for databricks-mcp-toolkit 0.2.0
File Interpreter ABI Platform Actions
databricks_mcp_toolkit-0.2.0-py3-none-any.whl Python 3 none any Details for databricks_mcp_toolkit-0.2.0-py3-none-any.whl

Total release size: 82.7 kB

Release files / databricks_mcp_toolkit-0.2.0.tar.gz

Download URL databricks_mcp_toolkit-0.2.0.tar.gz
Size 40.7 kB
Tags Source
SHA-256 checksum
How to use checksums
3ddaf27f273572fbfa65d39cfb1f9c06fcaf43a1c1a2794d01a4720113d26dc3
BLAKE2b-256 checksum
How to use checksums
0e4c968c8741ed26848c2d5051bab83f4d329e42d3a0b7d6eedc6afe994a9b6e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / databricks_mcp_toolkit-0.2.0-py3-none-any.whl

Download URL databricks_mcp_toolkit-0.2.0-py3-none-any.whl
Size 42.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
35b6924a5deb003a7877b1e081aff71c1f323e3d785075d0a345633dcaea2ef0
BLAKE2b-256 checksum
How to use checksums
c5909f48928a3690a142cc6ac155441d3b046c652adb4c759c0316eb6571ac2e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for databricks-mcp-toolkit 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for databricks_mcp_toolkit-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page