数据湖精灵MCP

Name: 数据湖精灵MCP
Author: alexxx-db

作者：alexxx-db9 星标更新：2025-05-13

安装使用来源：spider==github.com

项目介绍

Databricks Genie API MCP 服务器

该项目实现了一个模型上下文协议（MCP）服务器，该服务器公开了Databricks Genie API的功能作为工具。它允许您通过标准化接口将Databricks的无代码AI/BI助手功能与其他应用程序集成，从而能够对您的Databricks数据进行强大的自然语言查询。

对于详细的解释和示例用例，请参阅附带的博客文章。

功能

将Databricks Genie API功能作为MCP工具公开。
启用Databricks数据的自然语言查询。
启动和管理Genie对话。
创建和检索消息。
执行并获取由Genie生成的SQL查询结果。
使用Databricks进行安全认证。

先决条件

Python 3.10+
具有Genie访问权限和启用系统表（如果使用的话）的Databricks工作区。
启用了Databricks助手。
在Pro或Serverless SQL仓库上具有CAN USE权限。
访问与您的Genie空间相关的Unity目录数据。
一个兼容MCP的客户端应用程序，如Claude Desktop。

设置说明

克隆存储库（如果尚未执行）
```
# 如果需要添加克隆命令
```
导航到服务器目录
```
cd genie_api 
```
安装依赖项
```
pip install -r requirements.txt
```

配置认证

设置Databricks SDK连接到您的工作区所需的环境变量。在本目录（genie_api/）中创建一个.env文件或全局设置它们：

# --- .env 文件内容 ---

# 对于PAT认证（推荐用于开发）
# DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
# DATABRICKs_TOKEN=your-personal-access-token

# 或者使用服务主体进行OAuth（推荐用于生产）
DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
DATABRICKS_CLIENT_ID=your-client-id
DATABRICKS_CLIENT_SECRET=your-client-secret

# --- 结束 .env 文件内容 ---

确保将.env文件添加到您的.gitignore中！

本地运行服务器
```
python server.py
```
服务器将启动并通过标准输入/输出（stdio）监听连接。

与Claude Desktop一起使用

此MCP服务器旨在与MCP客户端（如Claude Desktop）一起使用。按照以下步骤进行连接：

安装Claude Desktop： 从官方网站下载并安装。
配置Claude Desktop：
- 打开Claude Desktop设置（菜单栏 -> Claude -> 设置...）。
- 转到开发者 -> 编辑配置。
- 在claude_desktop_config.json文件中的mcpServers对象中添加以下条目，并根据需要调整路径：
```
{
  "mcpServers": {
    "databricks-genie": {
      "command": "python", // 或者python3，或者Python可执行文件的完整绝对路径
      "args": [
        "/full/absolute/path/to/your/project/genie_api/server.py" 
      ],
      "workingDirectory": "/full/absolute/path/to/your/project/genie_api/" 
    }
    // ... 可能还有其他服务器 ...
  }
}
```
- 重要： 使用server.py和genie_api目录的完整绝对路径。
- 确保Claude Desktop可以访问Python command。
- workingDirectory确保服务器可以找到auth.py和您的.env文件。
重启Claude Desktop： 关闭并重新打开应用程序。
验证： 单击聊天输入中的锤子图标（工具）。您应该看到列出的databricks-genie工具（例如，start_conversation，create_message）。

现在您可以向Claude提问，如“我们上个月的DBU消耗是多少？”或“谁昨天访问了PII表？”，它将使用您本地服务器提供的工具来回答。

有关配置Claude Desktop的更多详细信息，请参阅Claude Desktop用户快速入门指南。

可用工具

start_conversation：在一个Genie空间开始一个新的对话。
create_message：在一个现有对话中创建一条新消息。
get_message：从对话中检索一条消息。
get_message_attachment_query_result：从消息附件中获取SQL查询结果。
execute_message_attachment_query：执行消息查询附件的SQL。
get_space：获取关于Genie空间的详细信息。
generate_download_full_query_result：启动完整的查询结果下载。
poll_message_until_complete：轮询消息直到其达到终端状态。

故障排除

认证问题：验证Databricks凭据（.env文件或环境变量）以及Databricks中的所需权限。
连接问题（Claude Desktop）：
- 确保claude_desktop_config.json中的绝对路径正确。
- 验证command指向有效的Python解释器。
- 检查Claude Desktop日志（~/Library/Logs/Claude/或%APPDATA%\Claude\logs）。查找mcp.log和mcp-server-databricks-genie.log。
- 尝试手动在genie_api目录下运行python server.py以检查错误。
SQL执行错误：确保服务主体或用户具有SQL仓库上的CAN USE权限，并且可以访问相关的Unity目录数据。

安全注意事项

凭证：永远不要硬编码凭证。使用环境变量（.env）或安全凭证存储。确保.env在您的.gitignore中。生产中使用服务主体进行OAuth。
MCP安全：此服务器在您的用户权限和Databricks凭证下本地运行。像Claude Desktop这样的客户端必须在执行工具之前获得用户同意（MCP安全规范）。
生产部署：为了更广泛的用途运行此服务器需要一个安全的托管策略。不要简单地暴露这个本地服务器。 与安全/DevOps合作确定适当的托管、网络控制，以及可能的MCP服务器级别的认证。托管环境需要安全访问Databricks凭证（例如，实例配置文件、托管秘密）。请参阅博客文章以获得更多讨论。
输入净化：信任传递给工具的Databricks SDK/API处理输入。

贡献

欢迎贡献！请打开一个问题或提交一个拉取请求。

许可

本软件由Databricks, Inc.提供特定许可。请参阅LICENSE文件以了解完全支配您使用此软件的条款和条件。