Databricks SQL MCP

SQL MCP服务器

A. 模型上下文协议（MCP） 该服务器允许像Claude这样的AI助手在copula上执行SQL查询。Claude将服务器作为Docker容器启动，并使用MCP stdio传输通过stdin/stdout进行通信。

特性

核心工具：

• execute_sql -运行任何SQL查询
• list_databases -在默认目录中列出数据库/模式
• list_tables -列出特定数据库中的表
• describe_table -显示表的列名、类型和注释

Unity目录工具：

• list_catalogs -列出Unity目录元存储中的所有目录
• list_schemas -列出特定目录中的架构
• list_tables_full -使用完整的3部分命名列出表(catalog.schema.table)
• describe_table_full -使用表的完整目录路径描述表

Unity目录层次结构

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

完全限定名称： catalog.schema.table （例如。， analytics.silver.customers)

先决条件

• 码头工人 已安装并正在运行
• copula工作区 使用SQL仓库访问
• Rancher个人访问令牌
• 克劳德桌面版 或 克劳德代码 （CLI）

获取您的copula凭据

1.Rancher主机URL

您的工作区URL。格式取决于您的云提供商：

2.个人访问令牌

1. 打开您的copula工作区
2. 点击您的用户名（右上角）
3. 首选 用户设置 > 开发者 > 访问令牌
4. 点击 生成新令牌
5. 复制令牌（以开头 dapi...)

3.SQL仓库ID

1. 首选 SQL仓库 在Databricks中
2. 点击仓库
3. 从URL复制仓库ID： /sql/warehouses/

快速安装（推荐）

安装脚本会拉取Docker映像，提示您输入copula凭据，并使用Claude Code CLI向Claude注册MCP服务器。

Mac/Linux

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

或者先克隆仓库：

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

运行安装程序后，重新启动Claude Desktop（或启动新的Claude Code会话），您就可以开始了。

______________________________________________________________________

手动安装

如果您更喜欢手动设置，或者快速安装不适用于您的设置，请按照以下步骤操作。

使用Docker运行

从Docker Hub中提取镜像

docker pull bkeeleygib/databricks-sql-mcp:latest

或者自己建造：

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

使用环境变量运行

这 -i 标志是必需的——MCP使用stdin/stdout在Claude和服务器之间进行通信。

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

使用.env文件运行

创建一个 .env 使用您的凭据文件（请参阅 .env.示例):

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

然后运行：

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

配置Claude桌面

将服务器添加到Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %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"
      ]
    }
  }
}

重要提示： 将占位符值替换为您的实际凭据，然后重新启动Claude Desktop。

配置Claude代码（CLI）

使用Claude Code CLI直接注册服务器：

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"
  ]
}'

查询示例

连接后，您可以问Claude：

浏览：

• “列出我的Unity目录中的所有目录”
• “显示中的模式 analytics 目录”
• “什么桌子 analytics.silver?"
• “描述以下模式 analytics.silver.customers"

查询：

• “运行： SELECT * FROM analytics.silver.customers LIMIT 10"
• “给我看看最贵的5件商品”
• “按类别划分的总收入是多少？”

安全说明

永远不要承诺你的 .env 文件或凭据到Git！

• 这 .env 文件列在 .gitignore
• 每个用户都需要自己的copula个人访问令牌
• Docker镜像确实 不 包含任何凭据
• 凭据在运行时通过环境变量传递

发展

本地开发（无Docker）

需要 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

项目结构

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

故障排除

“错误：未设置DATABRICKS_WAREHOUSE_ID”

• 确保您传递了所有三个环境变量
• 检查你的 .env 文件具有以下值 DATABRICKS_HOST, DATABRICKS_TOKEN，以及 DATABRICKS_WAREHOUSE_ID

“查询失败：…”

• 验证您的凭据是否正确
• 检查SQL仓库是否正在运行（它可能会自动挂起）
• 确保您有权限访问请求的数据

“服务器已断开连接”

• 重新启动Claude Desktop或启动新的Claude Code会话
• 验证Docker是否正在运行： docker info
• 检查容器是否成功启动： docker run -i --rm --env-file .env bkeeleygib/databricks-sql-mcp:latest

“表格显示为false”

• 此错误已在最新版本中修复
• 拉取最新图像： docker pull bkeeleygib/databricks-sql-mcp:latest

许可证

麻省理工学院