Databricks精灵API MCP服务器
该项目实现了一个模型上下文协议（MCP）服务器，该服务器将Databricks Genie API功能作为工具公开。它允许您通过一个标准化的界面将copula的无代码AI/BI助手功能与其他应用程序集成，从而能够对您的copula数据进行强大的自然语言查询。
有关详细说明和示例用例，请参阅随附的 博客文章.
特性
- 公开Databricks Genie API功能作为MCP工具。
- 启用对copula数据的自然语言查询。
- 启动并管理Genie对话。
- 创建和检索邮件。
- 执行并获取Genie生成的SQL查询结果。
- 使用copula进行安全身份验证。
先决条件
- Python 3.10+
- 启用了Genie访问和系统表（如果使用它们）的copula工作区。
- 已启用copula助手。
- 可以在Pro或无服务器SQL仓库上使用权限。
- 访问与Genie Space相关的Unity目录数据。
- MCP兼容的客户端应用程序，例如 克劳德桌面.
安装说明
- 克隆存储库 （如果你还没有）
# Add clone command if needed- 导航到服务器目录
cd genie_api - 再进行
pip install -r requirements.txt- 配置身份验证
设置所需的环境变量，以使copula SDK连接到您的工作区。创建一个 .env 此目录中的文件(genie_api/)或全局设置它们：
# --- .env file content ---
# For PAT authentication (recommended for development)
# DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
# DATABRICKS_TOKEN=your-personal-access-token
# Or for OAuth with service principal (recommended for production)
DATABRICKS_HOST=https://your-workspace.cloud.databricks.com
DATABRICKS_CLIENT_ID=your-client-id
DATABRICKS_CLIENT_SECRET=your-client-secret
# --- end .env file content ---*确保 .env 文件已添加到您的.gitignore！*
- 在本地运行服务器
python server.py服务器将启动并通过标准输入/输出（stdio）监听连接。
与Claude Desktop一起使用
此MCP服务器旨在与Claude Desktop等MCP客户端一起使用。按照以下步骤进行连接：
- 安装克劳德桌面： 从下载并安装 官方网站.
- 配置Claude桌面：
- 打开克劳德桌面设置（菜单栏->克劳德->设置…）。 - 转到开发人员->编辑配置。 - 将以下条目添加到 mcpServers 对象在 claude_desktop_config.json 文件，根据需要调整路径：
{
"mcpServers": {
"databricks-genie": {
"command": "python", // Or python3, or the full path to your python executable
"args": [
"/full/absolute/path/to/your/project/genie_api/server.py"
],
"workingDirectory": "/full/absolute/path/to/your/project/genie_api/"
}
// ... potentially other servers ...
}
}- 重要提示： 使用 完全绝对路径 向 server.py 和那个 genie_api 目录。 - 确保Python command 可通过Claude Desktop访问。 - 这 workingDirectory 确保服务器能够找到 auth.py 和你的 .env 文件。
- 重新启动克劳德桌面： 关闭并重新打开应用程序。
- 验证： 单击聊天输入中的锤子图标（工具）。你应该看看
databricks-genie列出的工具（例如。，start_conversation,create_message).
现在，您可以向Claude提问，例如“上个月我们的DBU消耗量是多少？”或“昨天谁访问了PII表？”，它将使用您本地服务器提供的工具。
有关配置Claude Desktop的更多详细信息，请参阅 Claude桌面用户的MCP快速入门.
可用工具
start_conversation：在精灵空间开始新的对话。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：轮询消息，直到它达到终端状态。
故障排除
- 身份验证问题：验证copula凭据(
.env文件或环境变量）和所需权限。 - 连接问题（Claude Desktop）:
- 确保绝对路径 claude_desktop_config.json 是正确的。 - 验证 command 指向一个有效的Python解释器。 - 检查克劳德桌面日志(~/Library/Logs/Claude/ 或 %APPDATA%\Claude\logs).寻找 mcp.log 和 mcp-server-databricks-genie.log. - 试着跑步 python server.py 从终端手动 genie_api 用于检查错误的目录。
- SQL执行错误：确保服务主体或用户在SQL仓库上具有CAN USE权限，并可以访问相关的Unity Catalog数据。
安全考虑
- 资格证书： 永远不要硬编码凭据。使用环境变量(
.env)或安全凭证存储。确保.env在你的.gitignore.将OAuth与服务主体一起用于生产。 - MCP安全： 此服务器在本地运行，具有用户的权限和copula凭据。像Claude Desktop这样的客户 必须 在执行工具之前获得用户同意(MCP安全规范).
- 生产部署： 运行此服务器以供更广泛的使用需要安全的托管策略。 不要简单地暴露此本地服务器。 与安全/DevOps合作，确定适当的托管、网络控制和潜在的MCP服务器级身份验证。托管环境需要安全访问copula凭据（例如，实例配置文件、托管密钥）。请参阅 博客文章 更多讨论。
- 输入消毒： 对于通过工具传递的输入处理，请信任Databricks SDK/neneneba API。
贡献
欢迎投稿！请打开问题或提交拉取请求。
许可证
此软件是根据Databricks，股份有限公司授予的特定许可证提供的。请参阅 许可证 有关使用本软件的完整条款和条件的文件。