databricks-mcp-toolkit 0.2.0__py3-none-any.whl

databricks_mcp_toolkit-0.2.0.dist-info/METADATA

@@ -0,0 +1,282 @@
+Metadata-Version: 2.5
+Name: databricks-mcp-toolkit
+Version: 0.2.0
+Summary: Model Context Protocol (MCP) server for Databricks: clusters, jobs, SQL, Unity Catalog, volumes and notebooks.
+Project-URL: Homepage, https://github.com/kshptl/Databricks-MCP-Server
+Project-URL: Repository, https://github.com/kshptl/Databricks-MCP-Server
+Project-URL: Issues, https://github.com/kshptl/Databricks-MCP-Server/issues
+Project-URL: Changelog, https://github.com/kshptl/Databricks-MCP-Server/blob/main/CHANGELOG.md
+Author: Kush Patel
+License-Expression: AGPL-3.0-only
+License-File: LICENSE
+Keywords: ai-agents,claude,databricks,llm,mcp,model-context-protocol,unity-catalog
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: databricks-sdk>=0.40
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pydantic>=2.7
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Databricks MCP Toolkit
+
+[![PyPI](https://img.shields.io/pypi/v/databricks-mcp-toolkit.svg)](https://pypi.org/project/databricks-mcp-toolkit/)
+[![Python](https://img.shields.io/pypi/pyversions/databricks-mcp-toolkit.svg)](https://pypi.org/project/databricks-mcp-toolkit/)
+[![CI](https://github.com/kshptl/Databricks-MCP-Server/actions/workflows/ci.yml/badge.svg)](https://github.com/kshptl/Databricks-MCP-Server/actions/workflows/ci.yml)
+[![License: AGPL-3.0](https://img.shields.io/badge/license-AGPL--3.0-blue.svg)](LICENSE)
+
+A [Model Context Protocol](https://modelcontextprotocol.io) 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](https://docs.astral.sh/uv/) (or pipx/pip).
+
+```bash
+# 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):
+
+```json
+{
+  "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
+
+```bash
+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:
+
+```bash
+databricks-mcp run --transport streamable-http --host 127.0.0.1 --port 8000
+```
+
+## Authentication
+
+Auth is delegated to [Databricks unified auth](https://docs.databricks.com/aws/en/dev-tools/auth/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
+
+```bash
+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.
+
+<!-- tools:start -->
+
+**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. |
+
+<!-- tools:end -->
+## 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
+
+```bash
+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](CONTRIBUTING.md) and [ARCHITECTURE.md](ARCHITECTURE.md). Releases are covered in [RELEASING.md](RELEASING.md).
+
+## License
+
+Dual-licensed:
+
+- **[AGPL-3.0-only](LICENSE)** 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.

databricks_mcp_toolkit-0.2.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+databricks_mcp/__init__.py,sha256=jPfz8_GWdn0USujrxFaufygn4KTt58vSDDuMGi4Ong4,308
+databricks_mcp/__main__.py,sha256=dBqv_lxHHG-u5Vf0DJgURddYNr-xFY9k9ea8U1iAEio,291
+databricks_mcp/cli.py,sha256=4KooaHQcqnsrM1bTLbHDOSEJdKt5ysInrJTqnYfZVLU,3863
+databricks_mcp/client.py,sha256=cIrolD4kmSDvUrQYK_6G4gTu8MyuXrtOFnw4_yN6YWE,7379
+databricks_mcp/config.py,sha256=HmXYv7QYKOkV7EBRktEuI5y7SBzlKvYVnc49qTrIJFc,1899
+databricks_mcp/server.py,sha256=rhL5wpH5jTy8zzZsJ71xi0N5pa_2GTcWATmx38XAS_0,27269
+databricks_mcp/api/__init__.py,sha256=ARHHhWrKk62Y1wAAQo0Rv-Ug5IyEz3o-ZGmTs2Hc7sg,640
+databricks_mcp/api/clusters.py,sha256=B7YAZMNdKE1PTU6JIRZ85L7B-85hFs4VTln7sY0V0Es,2689
+databricks_mcp/api/command_execution.py,sha256=u5YukjQ-TTUj88TC9iCwoD9AY3IA8tKbB_vQ-wF6RwY,3406
+databricks_mcp/api/dbfs.py,sha256=Eqiw0nS17eA5CMRoBCk9DhjX7SBM3ffjAwbAikADmeY,1488
+databricks_mcp/api/files.py,sha256=8uFbCIeYE6Tw4NZSRyncSbj-25qnHF9pzU0keHoEXLM,3386
+databricks_mcp/api/jobs.py,sha256=55mkkC3VRRSq8E6_ctYq35Oc7UAeY0OVQnBRbXZZfJw,5143
+databricks_mcp/api/sql.py,sha256=biqmJa44xnwpngCV03nB5vGEDi5UIVX3rvfZWcSVQgw,3512
+databricks_mcp/api/unity_catalog.py,sha256=H4pTQjJ0q-abXKTyrEzofU3BSrH-XyCO3evnKGZVjEs,2204
+databricks_mcp/api/warehouses.py,sha256=LGgJfyebuNlrSuhHQ3rgrC2GvB3XJ1k8uW2cuQlrhLA,1075
+databricks_mcp/api/workspace.py,sha256=gVUpoXOSixvN3frE4MIZCvihDHEuTEJE68483kxrgsg,2298
+databricks_mcp_toolkit-0.2.0.dist-info/METADATA,sha256=XcTkdNndJf3hK9NDt1gfLX0jPStEDidIqhdNyeV_Y3A,14111
+databricks_mcp_toolkit-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+databricks_mcp_toolkit-0.2.0.dist-info/entry_points.txt,sha256=J1Ofzc4HRj1EZlJ3A4jjSPwqGt1G55BffLqb5lB2J3s,59
+databricks_mcp_toolkit-0.2.0.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+databricks_mcp_toolkit-0.2.0.dist-info/RECORD,,

databricks_mcp_toolkit-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

databricks_mcp_toolkit-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+databricks-mcp = databricks_mcp.cli:main