mareana-databricks-mcp-server 0.1.1
Databricks MCP Server for exploring Unity Catalog - catalogs, schemas, tables, and data
License: MIT
Requires Python: >=3.10
Keywords: catalog, data-exploration, databricks, mcp, sql, unity-catalog

# Databricks MCP Server

A Model Context Protocol (MCP) server for exploring Databricks Unity Catalog. Browse catalogs, schemas, tables, and query sample data.

## Features

- 🔐 **Secure U2M Authentication** using Databricks CLI OAuth flow
- 📂 **List Catalogs** - Browse all available Unity Catalog catalogs
- 📁 **List Schemas** - Explore schemas within a catalog
- 📋 **List Tables** - View tables in a catalog.schema
- 📊 **Table Details** - Get column names, data types, and metadata
- 📝 **Sample Data** - Query sample rows from tables (5-50 rows)
- ♻️ **Token Refresh** - Gracefully handles token expiration

## Installation

### Using pip

```bash
pip install mareana-databricks-mcp-server
```

### Using uvx

```bash
uvx mareana-databricks-mcp-server
```

### From source

```bash
git clone https://github.com/mareana/databricks-mcp-server.git
cd databricks-mcp-server
pip install -e .
```

## Prerequisites

### 1. Install Databricks CLI

```bash
# Using pip
pip install databricks-cli

# Or using homebrew (macOS)
brew tap databricks/tap
brew install databricks
```

### 2. Authenticate with Databricks

The server uses U2M (User-to-Machine) OAuth authentication via the Databricks CLI:

```bash
# Login to your Databricks workspace
databricks auth login --host https://your-workspace.cloud.databricks.com

# Or with a named profile
databricks auth login --host https://your-workspace.cloud.databricks.com --profile my_profile
```

### 3. Verify Authentication

```bash
databricks auth token
# Should output a valid access token
```

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| `DATABRICKS_PROFILE` | Databricks CLI profile to use | `DEFAULT` |

### Example

```bash
# Use a specific profile
export DATABRICKS_PROFILE="my_workspace_profile"
```

## Usage

### Running the Server

**With Python:**
```bash
mareana-databricks-mcp-server
```

**With uvx:**
```bash
uvx mareana-databricks-mcp-server
```

**From source:**
```bash
python -m databricks_mcp_server.server
```

### MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "databricks": {
      "command": "uvx",
      "args": ["mareana-databricks-mcp-server"],
      "env": {
        "DATABRICKS_PROFILE": "my_profile"
      }
    }
  }
}
```

Or using Python directly:

```json
{
  "mcpServers": {
    "databricks": {
      "command": "python3",
      "args": ["-m", "databricks_mcp_server.server"],
      "env": {
        "DATABRICKS_PROFILE": "my_profile"
      }
    }
  }
}
```

## Available Tools

### who_am_i

Get the current authenticated Databricks user.

**Returns:** Username, display name, and email of the authenticated user.

**Example Response:**
```json
{
  "username": "user@example.com",
  "display_name": "John Doe",
  "active": true,
  "emails": ["user@example.com"]
}
```

### list_catalogs

List all available catalogs in Unity Catalog.

**Returns:** List of catalogs accessible to the current user.

**Example Response:**
```json
{
  "total_count": 3,
  "catalogs": [
    {"name": "main", "owner": "admin@example.com"},
    {"name": "dev", "owner": "admin@example.com"},
    {"name": "staging", "owner": "admin@example.com"}
  ]
}
```

### list_schemas

List all schemas in a specified catalog.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `catalog_name` | string | Yes | Name of the catalog |

**Example Response:**
```json
{
  "catalog": "main",
  "total_count": 2,
  "schemas": [
    {"name": "default", "full_name": "main.default"},
    {"name": "raw_data", "full_name": "main.raw_data"}
  ]
}
```

### list_tables

List all tables in a specified catalog and schema.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `catalog_name` | string | Yes | Name of the catalog |
| `schema_name` | string | Yes | Name of the schema |

**Example Response:**
```json
{
  "catalog": "main",
  "schema": "raw_data",
  "total_count": 2,
  "tables": [
    {"name": "users", "full_name": "main.raw_data.users", "table_type": "MANAGED"},
    {"name": "events", "full_name": "main.raw_data.events", "table_type": "EXTERNAL"}
  ]
}
```

### get_table_details

Get detailed information about a table including column names, data types, and metadata.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `catalog_name` | string | Yes | Name of the catalog |
| `schema_name` | string | Yes | Name of the schema |
| `table_name` | string | Yes | Name of the table |

**Example Response:**
```json
{
  "full_name": "main.raw_data.users",
  "table_type": "MANAGED",
  "data_source_format": "DELTA",
  "column_count": 3,
  "columns": [
    {"position": 1, "name": "id", "type": "LONG", "nullable": false},
    {"position": 2, "name": "name", "type": "STRING", "nullable": true},
    {"position": 3, "name": "created_at", "type": "TIMESTAMP", "nullable": true}
  ]
}
```

### get_sample_data

Get sample data from a table.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `catalog_name` | string | Yes | Name of the catalog |
| `schema_name` | string | Yes | Name of the schema |
| `table_name` | string | Yes | Name of the table |
| `limit` | integer | No | Number of rows (min: 5, max: 50, default: 10) |

**Example Response:**
```json
{
  "table": "main.raw_data.users",
  "warehouse_used": "Starter Warehouse",
  "row_count": 3,
  "columns": ["id", "name", "created_at"],
  "data": [
    {"id": 1, "name": "Alice", "created_at": "2024-01-01T00:00:00Z"},
    {"id": 2, "name": "Bob", "created_at": "2024-01-02T00:00:00Z"},
    {"id": 3, "name": "Charlie", "created_at": "2024-01-03T00:00:00Z"}
  ]
}
```

## Token Expiration Handling

The server gracefully handles token expiration. If your token expires, you'll receive a helpful message:

```
❌ Authentication failed. Your token may have expired.
Please re-authenticate using:
  databricks auth login --profile my_profile
```

Simply run the suggested command to refresh your authentication.

## Troubleshooting

### "No SQL warehouses available"

Sample data queries require an active SQL warehouse. Contact your Databricks admin to ensure you have access to a warehouse.

### "Permission denied"

You may not have access to the specified catalog/schema/table. Check your Unity Catalog permissions with your admin.

### "Table not found"

Verify the catalog, schema, and table names are correct. Use `list_catalogs`, `list_schemas`, and `list_tables` to explore available objects.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Author

Shashanka G - [shashanka.g@mareana.com](mailto:shashanka.g@mareana.com)