MCP Databricks

Databricks MCP 服务器

一个用于Databricks集成的模型上下文协议（MCP）服务器，使大型语言模型（LLMs）能够与Databricks工作区交互、执行SQL查询并检查表结构。

特点/特性

• 表模式检查获取关于表结构的详细信息，包括列名、数据类型和注释
• SQL查询执行在Databricks上执行SQL查询并检索结果
• 基于环境的配置使用环境变量实现安全的凭证管理

先决条件

• Python 3.13 或更高版本
• 紫外线 包管理器
• 配备以下功能的Databricks工作区：

- 工作区URL - 个人访问令牌或服务主体令牌 - SQL 仓库 HTTP 路径

安装

1. 克隆仓库：

git clone 
cd mcp-databricks

1. 安装依赖项：

uv sync

1. 配置环境变量：

cp .env.example .env

编辑 .env 并填写您的Databricks凭据：

DATABRICKS_HOST=https://your-workspace.databricks.com
DATABRICKS_TOKEN=your-access-token
DATABRICKS_HTTP_PATH=/sql/1.0/warehouses/your-warehouse-id

使用方法

运行MCP服务器

该软件包提供了一个可执行命令 mcp-databricks 你可以运行：

uv run mcp-databricks

或者，您可以直接运行主模块：

uv run python main.py

使用MCP CLI进行开发：

uv run mcp dev main.py

使用MCP Inspector进行测试

MCP Inspector 是一款强大的工具，用于测试和调试您的 MCP 服务器。它提供了一个基于网页的界面，以便与您的服务器工具进行交互。

启动检查器：

npx @modelcontextprotocol/inspector uv run mcp-databricks

或者直接使用主模块：

npx @modelcontextprotocol/inspector uv run python main.py

这将：

1. 启动您的MCP服务器
2. 启动 Inspector 网页界面（通常位于 http://localhost:5173）
3. 允许您在浏览器中交互式地测试工具

使用检查器：

• 查看所有可用工具及其参数
• 执行带有自定义输入的工具
• 查看实时响应和结果
• 调试连接和身份验证问题

示例工作流程：

1. 使用上述命令启动检查器
2. 在浏览器中打开提供的URL
3. 选择 get_table_schema 工具
4. 输入参数： catalog="main"， schema="default"， table="your_table"
5. 点击“运行”以查看表结构响应
6. 试试这个 execute_sql_query 一个能执行简单查询的工具，比如 SELECT * FROM main.default.your_table LIMIT 10

可用工具

1. 获取表结构

获取Databricks表的架构，包括列名和数据类型。

参数：

• catalog (字符串)：目录名称
• schema (字符串)：模式名称
• table (字符串)：表名

返回：

{
  "catalog": "main",
  "schema": "default",
  "table": "users",
  "full_name": "main.default.users",
  "columns": [
    {
      "name": "id",
      "type": "bigint",
      "comment": "User ID"
    },
    {
      "name": "name",
      "type": "string",
      "comment": "User name"
    }
  ]
}

2. 执行SQL查询

在Databricks上执行SQL查询并返回结果。

重要提示： 当查询表时，你 必须 使用完整的三级命名空间格式： catalog.schema.table （例如。， main.default.users）。 Do（在音乐中表示“do”音，在命令或指示中可译为“做”） 否（逻辑运算符，表示非） 使用两级格式，如 schema.table 因为它在 Unity Catalog 中会失败。

参数：

• query （字符串）：要执行的SQL查询。必须使用完整的表名（目录.模式.表）
• max_rows （整数，可选）：要返回的最大行数（默认：1000）

返回值：

{
  "query": "SELECT * FROM main.default.users LIMIT 10",
  "columns": ["id", "name", "email"],
  "rows": [
    {"id": 1, "name": "Alice", "email": "alice@example.com"},
    {"id": 2, "name": "Bob", "email": "bob@example.com"}
  ],
  "row_count": 2,
  "truncated": false
}

3. 列出表（或“显示表列表”）

列出Databricks目录和架构中的所有表。

参数：

• catalog （字符串，可选）：目录名称（如果未提供，则使用 DATABRICKS_CATALOG 环境变量）
• schema (字符串，可选)：模式名称（如果未提供，则使用 DATABRICKS_SCHEMA 环境变量）

返回值：

{
  "catalog": "main",
  "schema": "default",
  "tables": [
    {"name": "users", "is_temporary": false},
    {"name": "orders", "is_temporary": false}
  ],
  "table_count": 2,
  "usage_hint": "To query these tables, use the full name: main.default."
}

配置

环境变量

以下环境变量是必需的：

获取Databricks凭据

1. 工作区URL在您的Databricks工作区URL中找到（例如。， https://your-workspace.databricks.com）

1. 访问令牌:

- 进入用户设置 > 开发者 > 访问令牌 - 点击“生成新令牌” - 复制生成的令牌

1. HTTP 路径：

- 在您的Databricks工作区中导航至SQL仓库 - 选择您的仓库 - 转到“连接详情”选项卡 - 复制HTTP路径

发展

项目结构

mcp-databricks/
├── main.py              # MCP server implementation
├── pyproject.toml       # Project dependencies
├── .env.example         # Environment variables template
├── .env                 # Local configuration (gitignored)
└── README.md            # This file

依赖项

• Databricks SDK（数据砖块软件开发工具包）官方Databricks Python SDK
• fastmcp（这个词汇在常规语境下可能不是一个广泛认知的英文单词，但根据其构成，可以尝试翻译为）：快速MCP（MCP可能代表某种特定概念或缩写，具体含义需根据上下文确定，此处仅作泛指翻译）用于构建MCP服务器的FastMCP框架
• python-dotenv（用于在Python中加载环境变量的库）环境变量管理

添加新工具

要添加新工具，请在（相应位置）对其进行定义 main.py 使用 @mcp.tool() 装饰器：

@mcp.tool()
def your_tool_name(param1: str, param2: int) -> dict:
    """
    Tool description here.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value
    """
    # Implementation
    return {"result": "data"}

安全注意事项

• 永远不要让你的（情感/承诺/秘密等，根据上下文具体确定） .env 将文件提交到版本控制系统
• 在生产部署中使用服务主体令牌
• 将令牌权限限制为仅必要的权限
• 定期轮换访问令牌
• 使用带有适当访问控制的SQL数据仓库

故障排除

连接问题

如果您遇到连接错误：

1. 验证您的 DATABRICKS_HOST 是正确的，并且包含 https://
2. 检查您的访问令牌是否有效且未过期
3. 确保您的SQL数据仓库正在运行
4. 验证HTTP路径是否与您的SQL数据仓库匹配

查询执行错误

• “Table not found errors” 翻译成中文是：“表未找到错误”始终使用完整的三级命名空间 catalog.schema.table 在SQL查询中

- ✅ 正确： SELECT * FROM main.default.users - ❌ 错误： SELECT * FROM default.users 或者 SELECT * FROM users

• 确保用户/服务主体对目录、模式和表具有适当的权限
• 如果使用三级命名空间（catalog.schema.table），请确保已启用 Unity Catalog
• 验证SQL语法是否与Databricks SQL兼容

许可证

\[在此添加您的许可证\]

做出贡献

\[在此添加贡献指南\]