npm package: @squadbase/mcp-databricks
Description: MCP Server for Databricks SQL and Workspace API
Latest version: 0.0.1

# @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

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

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

## Usage

### Direct Execution

```bash
npx -y @squadbase/mcp-databricks
```

### Via Launcher

```bash
npx -y @squadbase/mcp databricks
```

## MCP Client Configuration

Add to your `mcp.json`:

**Via Launcher (recommended):**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "ok": true,
  "server": "mcp-databricks",
  "version": "0.0.1"
}
```

### databricks_info

Test Databricks connectivity and get user info.

**Input:** None

**Output (success):**
```json
{
  "ok": true,
  "connected": true,
  "host": "your-workspace.cloud.databricks.com",
  "user": "user@example.com",
  "user_id": "12345",
  "groups": ["users", "admins"]
}
```

**Output (failure):**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "ok": true,
  "catalogs": [
    {
      "name": "main",
      "comment": "Main catalog",
      "type": "MANAGED_CATALOG",
      "owner": "admin"
    }
  ]
}
```

### list_schemas

List all schemas in a catalog.

**Input:**
```json
{
  "catalog": "main"
}
```

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

### list_tables

List all tables in a schema.

**Input:**
```json
{
  "catalog": "main",
  "schema": "default"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "catalog": "main",
  "schema": "default",
  "table": "users"
}
```

**Output:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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