Databricks MCP Server

How to use

Use the MCP server with your preferred MCP client to let an AI agent explore Unity Catalog, inspect table structures, follow data lineage, and run SQL queries. Start by discovering available catalogs, then drill into schemas and tables to gather context before constructing and running queries. When the agent needs to execute data retrieval or validation, use the SQL execution capability to fetch results and verify expectations.

How to install

Prerequisites: ensure you have Python 3.10 or newer installed on your system. You may also need a development toolchain for local or containerized runs.

pip install -r requirements.txt

Optionally, if you plan to run using the uvx runtime, install the dependencies via the uv engine as shown.

uv pip install -r requirements.txt

Create an environment file with your Databricks credentials for convenient loading of variables.

DATABRICKS_HOST="your-databricks-instance.cloud.databricks.com"
DATABRICKS_TOKEN="your-databricks-personal-access-token"
DATABRICKS_SQL_WAREHOUSE_ID="your-sql-warehouse-id"

If you prefer, set the environment variables directly in your shell instead of using a .env file.

export DATABRICKS_HOST="your-databricks-instance.cloud.databricks.com"
export DATABRICKS_TOKEN="your-databricks-personal-access-token"
export DATABRICKS_SQL_WAREHOUSE_ID="your-sql-warehouse-id"

Additional sections

Configuration and security notes help you run the MCP server safely and effectively. The server relies on a Databricks access token with appropriate Unity Catalog permissions and, for SQL lineage or execution, access to a SQL Warehouse. It includes tools to list catalogs, describe catalogs/schemas/tables, view table columns, and execute SQL through the Databricks SDK.

Running the server

Stand-alone mode lets you test the MCP server locally. Use a Python command to start the server directly and connect with an MCP client.

python main.py

Using with Cursor

If you use Cursor as your agent runner, configure the MCP server in Cursor’s settings. The following examples show how to start the server from a local path using uv or directly with Python.

{
  "mcpServers": {
    "databricks": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/mcp-databricks-server",
        "run",
        "main.py"
      ]
    }
  }
}

{
  "mcpServers": {
    "databricks": {
      "command": "python",
      "args": [
        "/path/to/your/mcp-databricks-server/main.py"
      ]
    }
  }
}

Example Usage Workflow (for an LLM Agent)

An LLM agent can iteratively explore UC metadata and lineage, then formulate and run SQL queries. Start by listing catalogs, describe a catalog to see its schemas, drill into a schema to list tables, then describe a table to view columns and lineage. If needed, fetch detailed lineage to locate notebooks and jobs that process the data, and finally execute a SQL query to retrieve results.

Managing Metadata as Code with Terraform

You can define Unity Catalog metadata as code for versioning and automation. Use Terraform to declare catalogs and schemas, then apply changes to keep your metadata under control. Import existing Unity Catalog assets if you already have them, then manage descriptions and comments through Terraform configurations.

resource "databricks_catalog" "prod_catalog" {
  name          = "prod"
  comment       = "Main production catalog for all enterprise data."
  storage_root  = var.default_catalog_storage_root
  force_destroy = false
}

resource "databricks_schema" "prod_raw" {
  catalog_name = databricks_catalog.prod_catalog.name
  name         = "raw"
  comment      = "Raw data before any transformations."
}

resource "databricks_schema" "prod_bi_conformed" {
  catalog_name = databricks_catalog.prod_catalog.name
  name         = "bi_conformed"
  comment      = "Conformed (silver) schema for BI."
}

resource "databricks_schema" "prod_bi_modeled" {
  catalog_name = databricks_catalog.prod_catalog.name
  name         = "bi_modeled"
  comment      = "Modeled (gold) schema for BI."
}

Handling Long-Running Queries

The SQL execution tool uses the Databricks SDK with a wait timeout of 50 seconds for synchronous-like results. Very long-running queries may require additional handling beyond the default timeout.

Dependencies

Key dependencies include the Databricks SDK for REST API access and Unity Catalog, python-dotenv for environment loading, the MCP framework for model context communication, and asyncio/httpx for asynchronous and HTTP operations.

list_uc_catalogs

Lists all Unity Catalogs with names, descriptions, and types to help you discover data sources.

describe_uc_catalog

Provides a summary of a specific Unity Catalog, listing its schemas with names and descriptions.

describe_uc_schema

Shows detailed information about a schema, including tables and optional column details to aid in query construction.

describe_uc_table

Describes a specific Unity Catalog table with optional comprehensive lineage, including upstream/downstream tables and related notebooks and jobs.

execute_sql_query

Executes a SQL query against the Databricks SQL Warehouse and returns formatted results.