Databricks SQL MCP Server

A Model Context Protocol (MCP) server that lets AI assistants like Claude execute SQL queries on Databricks. Claude launches the server as a Docker container and communicates over stdin/stdout using the MCP stdio transport.

Features

Core Tools:

execute_sql - Run any SQL query against a Databricks SQL Warehouse
list_databases - List databases/schemas in the default catalog
list_tables - List tables in a specific database
describe_table - Show column names, types, and comments for a table

Unity Catalog Tools:

list_catalogs - List all catalogs in the Unity Catalog metastore
list_schemas - List schemas within a specific catalog
list_tables_full - List tables using full 3-part naming (catalog.schema.table)
describe_table_full - Describe a table using its full catalog path

Unity Catalog Hierarchy

CATALOG (e.g., analytics)
  └── SCHEMA/DATABASE (e.g., silver)
      └── TABLE (e.g., customers)

Fully qualified name: catalog.schema.table (e.g., analytics.silver.customers)

Prerequisites

Docker installed and running
Databricks workspace access with a SQL Warehouse
Databricks personal access token
Claude Desktop or Claude Code (CLI)

Getting Your Databricks Credentials

1. Databricks Host URL

Your workspace URL. The format depends on your cloud provider:

| Cloud | Example URL | |-------|------------| | Azure | https://adb-1234567890.azuredatabricks.net | | AWS | https://my-workspace.cloud.databricks.com | | GCP | https://my-workspace.gcp.databricks.com |

2. Personal Access Token

Open your Databricks workspace
Click your username (top-right)
Go to User Settings > Developer > Access tokens
Click Generate new token
Copy the token (starts with dapi...)

3. SQL Warehouse ID

Go to SQL Warehouses in Databricks
Click on a warehouse
Copy the warehouse ID from the URL: /sql/warehouses/<this-id>

Quick Install (Recommended)

The install scripts pull the Docker image, prompt for your Databricks credentials, and register the MCP server with Claude using the Claude Code CLI.

Mac / Linux

curl -fsSL https://raw.githubusercontent.com/benguy1000/databricks-sql-mcp/master/install.sh | bash

Or clone the repo first:

git clone https://github.com/benguy1000/databricks-sql-mcp.git
cd databricks-sql-mcp
chmod +x install.sh
./install.sh

Windows (PowerShell)

git clone https://github.com/benguy1000/databricks-sql-mcp.git
cd databricks-sql-mcp
.\install.bat

After running the installer, restart Claude Desktop (or start a new Claude Code session) and you're ready to go.

Manual Installation

If you prefer to set things up manually, or if the quick install doesn't work for your setup, follow the steps below.

Running with Docker

Pull the Image from Docker Hub

docker pull bkeeleygib/databricks-sql-mcp:latest

Or build it yourself:

docker build -t bkeeleygib/databricks-sql-mcp .

Run with Environment Variables

The -i flag is required -- MCP uses stdin/stdout for communication between Claude and the server.

docker run -i --rm \
  -e DATABRICKS_HOST="https://your-workspace.azuredatabricks.net" \
  -e DATABRICKS_TOKEN="dapi1234567890abcdef" \
  -e DATABRICKS_WAREHOUSE_ID="abc123def456" \
  bkeeleygib/databricks-sql-mcp:latest

Run with .env File

Create a .env file with your credentials (see .env.example):

DATABRICKS_HOST=https://your-workspace.azuredatabricks.net
DATABRICKS_TOKEN=dapi1234567890abcdef
DATABRICKS_WAREHOUSE_ID=abc123def456

Then run:

docker run -i --rm --env-file .env bkeeleygib/databricks-sql-mcp:latest

Configuring Claude Desktop

Add the server to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "databricks-sql": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "DATABRICKS_HOST=https://your-workspace.azuredatabricks.net",
        "-e", "DATABRICKS_TOKEN=dapi1234567890abcdef",
        "-e", "DATABRICKS_WAREHOUSE_ID=abc123def456",
        "bkeeleygib/databricks-sql-mcp:latest"
      ]
    }
  }
}

Important: Replace the placeholder values with your actual credentials, then restart Claude Desktop.

Configuring Claude Code (CLI)

Use the Claude Code CLI to register the server directly:

claude mcp add-json databricks-sql '{
  "command": "docker",
  "args": [
    "run", "-i", "--rm",
    "-e", "DATABRICKS_HOST=https://your-workspace.azuredatabricks.net",
    "-e", "DATABRICKS_TOKEN=dapi1234567890abcdef",
    "-e", "DATABRICKS_WAREHOUSE_ID=abc123def456",
    "bkeeleygib/databricks-sql-mcp:latest"
  ]
}'

Example Queries

Once connected, you can ask Claude:

Browsing:

"List all catalogs in my Unity Catalog"
"Show me the schemas in the analytics catalog"
"What tables are in analytics.silver?"
"Describe the schema of analytics.silver.customers"

Querying:

"Run: SELECT * FROM analytics.silver.customers LIMIT 10"
"Show me the top 5 most expensive items"
"What's the total revenue by category?"

Security Notes

Never commit your .env file or credentials to Git!

The .env file is listed in .gitignore
Each user needs their own Databricks personal access token
The Docker image does not contain any credentials
Credentials are passed at runtime via environment variables

Development

Local Development (without Docker)

Requires Python 3.11+.

# Install dependencies
pip install -r requirements.txt

# Create .env file with your credentials
cp .env.example .env
# Edit .env with your values

# Run the server
python server.py

Project Structure

server.py          # MCP server implementation (FastMCP + Databricks SDK)
requirements.txt   # Python dependencies (pinned to major versions)
Dockerfile         # Docker image definition
install.sh         # Quick installer for Mac/Linux
install.bat        # Quick installer for Windows
.env.example       # Template for environment variables

Troubleshooting

"Error: DATABRICKS_WAREHOUSE_ID not set"

Make sure you passed all three environment variables
Check that your .env file has values for DATABRICKS_HOST, DATABRICKS_TOKEN, and DATABRICKS_WAREHOUSE_ID

"Query failed: ..."

Verify your credentials are correct
Check that the SQL Warehouse is running (it may be auto-suspended)
Ensure you have permissions to access the requested data

"Server disconnected"

Restart Claude Desktop or start a new Claude Code session
Verify Docker is running: docker info
Check that the container starts successfully: docker run -i --rm --env-file .env bkeeleygib/databricks-sql-mcp:latest

"Tables show as false"

This bug has been fixed in the latest version
Pull the latest image: docker pull bkeeleygib/databricks-sql-mcp:latest

License

MIT

MCP Servers