Skip to main content
Glama
Agent-Hellboy

Databricks MCP

by Agent-Hellboy
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Databricks MCP

Read-only Model Context Protocol server for Databricks. It exposes catalog metadata and bounded SQL tools over Streamable HTTP while preserving the caller's identity through an OAuth-protected resource server.

Authorization is optional in MCP, but this service requires it in production because it exposes private workspace data. The authorization server may be self-hosted or provided by a third party. See docs/authorization.md.

Tools

Area

Tools

Catalog

list_catalogs, list_schemas, list_tables, describe_table, search_tables

SQL

run_readonly_sql, sample_table

Warehouses

list_warehouses

SQL is limited to one SELECT, WITH, SHOW, DESCRIBE, or EXPLAIN statement. Results are bounded, table sampling requires a three-part Unity Catalog identifier, and no write, job, cluster, DBFS, or secret tools are exposed.

Related MCP server: DB MCP Gateway

Requirements

  • Python 3.12+

  • A Databricks workspace

  • An MCP-compatible OAuth authorization server

  • Network access to fetch the pinned mcp-auth-client dependency from GitHub

Configuration

Copy deploy/service.env.example and set the deployment-specific values:

Variable

Purpose

DATABRICKS_HOST

HTTPS Databricks workspace URL

PUBLIC_BASE_URL / MCP_SERVER_URL

Public service base URL; /mcp is appended for the MCP resource

MCP_AUTH_ISSUER

Authorization-server issuer

MCP_AUTH_JWKS_URI

JWKS endpoint for access-token validation

MCP_AUTH_TOKEN_ENDPOINT

Optional downstream token-exchange endpoint

MCP_AUTH_CLIENT_PRIVATE_KEY_FILE

Resource-server exchange key

MCP_AUTH_CLIENT_KEY_ID_FILE

Exchange-key identifier

DATABRICKS_REQUIRED_GROUP

Required Databricks group

DATABRICKS_ALLOWED_WAREHOUSE_IDS

Explicit warehouse allowlist

MCP_ALLOWED_HOSTS

Allowed Host header values, comma-separated. Must match the incoming Host header exactly, including the port whenever the service is reached on a non-standard one (mcp.example.com:6328 for a direct port, vs. the bare mcp.example.com a standard-port HTTPS reverse proxy sends). The default only covers MCP_PORT; remapping the published port without updating this is the classic way to turn a healthy deployment into a 421.

MCP_SERVER_WEBSITE

Required. Shown to users in client UI when authorizing. Startup fails on an example.com placeholder, since it would point users at a domain you don't control.

MCP_SERVER_DISPLAY_NAME

Server name shown to clients (default Databricks MCP)

MCP_PATH

Where the MCP endpoint is mounted below PUBLIC_BASE_URL (default /mcp). This is also the token audience and the path the protected-resource metadata is published under, so changing it moves all three together; the authorization server must issue tokens for the same PUBLIC_BASE_URL + MCP_PATH.

MCP_HOST / MCP_PORT

Listen address (defaults 127.0.0.1 / 6328; the container image sets MCP_HOST=0.0.0.0)

MCP_LOG_LEVEL

Level for this service's own loggers and uvicorn's (default info; debug shows per-request auth decisions)

MCP_MAX_ROWS / MCP_MAX_SAMPLE_ROWS / MCP_SQL_WAIT_TIMEOUT

Query bounds (defaults 200 / 100 / 10s). MCP_MAX_SAMPLE_ROWS is a ceiling on the caller's requested sample size, never a floor.

list_warehouses only ever returns warehouses already on that allowlist, so run scripts/list_all_warehouses.py once, directly against the workspace, to find the IDs to put in it — see Bootstrapping DATABRICKS_ALLOWED_WAREHOUSE_IDS.

Keep real credentials, tokens, keys, and deployment env files out of Git.

Run locally

uv run uvicorn mcp_databricks.server:app --host 127.0.0.1 --port 6328

Or:

python -m mcp_databricks

The MCP endpoint is /mcp by default. The canonical ASGI entrypoint is mcp_databricks.server:app.

Development checks

ruff check .
ruff format --check .
python -m compileall -q mcp_databricks tests
uv run pytest

The first three checks run in public CI without service credentials. uv sync fetches the pinned authorization-client SDK before running the full test suite.

Release

Push a tag such as v0.2.3; the release workflow reruns validation, builds the Python distributions, and publishes a GitHub Release with the artifacts.

Deployment

  • Docker: build deploy/Dockerfile, inject a secret-managed env file, and mount the resource-server key read-only.

  • Kubernetes: run the container as a non-root Deployment, store env values and keys in Secrets, and expose it through an HTTPS Ingress.

  • docs/authorization.md: MCP OAuth flow and provider integration

  • deploy/README.md: Docker and reverse-proxy checklist

  • deploy/service.env.example: neutral configuration template

The authorization server owns login, consent, client registration, token issuance, and signing keys. This repository owns the Databricks MCP tools, resource-server policy, and downstream workspace integration.

This server cannot be deployed

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

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • BigQuery MCP Server

    amenke-lang
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables read-only interaction with Google BigQuery, including SQL queries, dataset/table listing, schema retrieval, table preview, and metadata access via service account authentication.
    -

  • DB MCP Gateway

    mdadul
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides read-only access to databases for MCP-compatible AI tools, allowing schema exploration and SELECT queries without exposing credentials or risking data changes.
    69 npm
    3
    MIT

  • DuckDB MCP Server

    poovenp
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables running read-only SQL queries and exploring DuckDB databases through MCP tools like listing tables, describing schemas, and fetching paginated data.
    -