@squadbase/mcp-databricks

MCP (Model Context Protocol) server for Databricks SQL and Unity Catalog.

Features

• Execute SQL queries against Databricks SQL warehouses
• Browse Unity Catalog (catalogs, schemas, tables)
• Inspect table schemas and sample data
• Designed for AI/LLM data analysis workflows

Installation

# No installation needed - use npx
npx -y @squadbase/mcp-databricks

# Or install globally
npm install -g @squadbase/mcp-databricks
mcp-databricks

Usage

Direct Execution

npx -y @squadbase/mcp-databricks

Via Launcher

npx -y @squadbase/mcp databricks

MCP Client Configuration

Add to your mcp.json:

Via Launcher (recommended):

{
  "mcpServers": {
    "databricks": {
      "command": "npx",
      "args": ["-y", "@squadbase/mcp", "databricks"],
      "env": {
        "DATABRICKS_HOST": "your-workspace.cloud.databricks.com",
        "DATABRICKS_TOKEN": "dapi...",
        "DATABRICKS_HTTP_PATH": "/sql/1.0/warehouses/abc123def456"
      }
    }
  }
}

Direct:

{
  "mcpServers": {
    "databricks": {
      "command": "npx",
      "args": ["-y", "@squadbase/mcp-databricks"],
      "env": {
        "DATABRICKS_HOST": "your-workspace.cloud.databricks.com",
        "DATABRICKS_TOKEN": "dapi...",
        "DATABRICKS_HTTP_PATH": "/sql/1.0/warehouses/abc123def456"
      }
    }
  }
}

Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | DATABRICKS_HOST | Workspace hostname (e.g., your-workspace.cloud.databricks.com) | Yes | | DATABRICKS_TOKEN | Personal access token | Yes | | DATABRICKS_HTTP_PATH | SQL warehouse HTTP path (e.g., /sql/1.0/warehouses/abc123) | For SQL queries |

Available Tools

ping

Health check - returns server name and version.

Input: None

Output:

{
  "ok": true,
  "server": "mcp-databricks",
  "version": "0.0.1"
}

databricks_info

Test Databricks connectivity and get user info.

Input: None

Output (success):

{
  "ok": true,
  "connected": true,
  "host": "your-workspace.cloud.databricks.com",
  "user": "[email protected]",
  "user_id": "12345",
  "groups": ["users", "admins"]
}

Output (failure):

{
  "ok": false,
  "connected": false,
  "error": "Missing required environment variables...",
  "required_env": ["DATABRICKS_HOST", "DATABRICKS_TOKEN", "DATABRICKS_HTTP_PATH"]
}

execute_sql

Execute a SQL query against Databricks SQL warehouse.

Input:

{
  "query": "SELECT * FROM catalog.schema.table LIMIT 10",
  "catalog": "main",
  "schema": "default",
  "max_rows": 1000
}

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | query | string | Yes | SQL query to execute | | catalog | string | No | Catalog name | | schema | string | No | Schema name | | max_rows | number | No | Maximum rows to return (default: 1000) |

Output:

{
  "ok": true,
  "status": "SUCCEEDED",
  "query": "SELECT * FROM ...",
  "warehouse_id": "abc123",
  "result": {
    "columns": ["id", "name", "created_at"],
    "rows": [["1", "Alice", "2024-01-01"], ...],
    "row_count": 10
  }
}

list_catalogs

List all available catalogs in Unity Catalog.

Input: None

Output:

{
  "ok": true,
  "catalogs": [
    {
      "name": "main",
      "comment": "Main catalog",
      "type": "MANAGED_CATALOG",
      "owner": "admin"
    }
  ]
}

list_schemas

List all schemas in a catalog.

Input:

{
  "catalog": "main"
}

Output:

{
  "ok": true,
  "catalog": "main",
  "schemas": [
    {
      "name": "default",
      "comment": "",
      "owner": "admin"
    }
  ]
}

list_tables

List all tables in a schema.

Input:

{
  "catalog": "main",
  "schema": "default"
}

Output:

{
  "ok": true,
  "catalog": "main",
  "schema": "default",
  "tables": [
    {
      "name": "users",
      "type": "MANAGED",
      "comment": "User data"
    }
  ]
}

describe_table

Get detailed information about a table including columns and schema.

Input:

{
  "catalog": "main",
  "schema": "default",
  "table": "users"
}

Output:

{
  "ok": true,
  "full_name": "main.default.users",
  "table_type": "MANAGED",
  "owner": "admin",
  "comment": "User data",
  "columns": [
    {
      "name": "id",
      "type": "LONG",
      "nullable": false,
      "comment": "Primary key"
    },
    {
      "name": "name",
      "type": "STRING",
      "nullable": true,
      "comment": ""
    }
  ],
  "created_at": 1704067200000,
  "updated_at": 1704153600000
}

sample_table

Get sample rows from a table for data exploration.

Input:

{
  "catalog": "main",
  "schema": "default",
  "table": "users",
  "limit": 10
}

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | catalog | string | Yes | Catalog name | | schema | string | Yes | Schema name | | table | string | Yes | Table name | | limit | number | No | Number of rows to sample (default: 10) |

Output:

{
  "ok": true,
  "full_name": "main.default.users",
  "limit": 10,
  "columns": ["id", "name", "created_at"],
  "sample_rows": [["1", "Alice", "2024-01-01"], ...],
  "row_count": 10
}

License

MIT