内容
# 自定义 Databricks MCP 服务器，用于 Claude Desktop
一个本地只读模型上下文协议（MCP）服务器，通过 Databricks REST API 将 Claude Desktop 连接到 Azure Databricks 工作区。
该项目的目标是让 Claude 通过安全的只读工具检查 Databricks 工作区元数据、笔记本、作业、作业运行和集群。
## 概述
Databricks Genie MCP 对于在配置的数据空间上提出自然语言问题很有用，但它不检查笔记本、源代码、作业、集群或工作区历史。
此自定义 MCP 服务器通过将选定的 Databricks REST API 调用作为 Claude Desktop 工具公开，从而填补了这一空白。
## 功能
* 列出 Databricks 工作区文件夹和对象
* 将 Databricks 笔记本导出为源代码
* 列出 Databricks 作业
* 列出最近的作业运行
* 列出 Databricks 集群
* 为 Claude Desktop 提供只读 Databricks 工作区检查工具
## 向 Claude 公开的工具
服务器公开了以下 MCP 工具：
| 工具名称 | 描述 |
| --- | --- |
| `list_workspace` | 列出给定路径下的 Databricks 工作区对象 |
| `export_notebook` | 将 Databricks 笔记本导出为源代码 |
| `list_jobs` | 列出 Databricks 作业 |
| `list_job_runs` | 列出最近的 Databricks 作业运行 |
| `list_clusters` | 列出 Databricks 集群 |
| `summarize_workspace_start` | 提供给定路径下工作区对象的快速摘要 |
## 项目结构
```text
databricks-mcp/
├── server.py
├── .env
├── .env.example
├── .gitignore
└── README.md
```
重要：`.env` 不能提交到 GitHub。
## 要求
* Windows、macOS 或 Linux
* Python 3.10 或更高版本
* Claude Desktop
* Azure Databricks 工作区
* Databricks 个人访问令牌
* Git（如果发布项目到 GitHub）
Python 包：
```text
mcp
requests
python-dotenv
```
## 设置
### 1. 克隆或创建项目文件夹
Windows 示例：
```powershell
cd C:\
mkdir Eli_Projects
cd C:\Eli_Projects
mkdir databricks-mcp
cd databricks-mcp
```
如果文件夹已经存在：
```powershell
cd C:\Eli_Projects\databricks-mcp
```
### 2. 创建 Python 虚拟环境
```powershell
python -m venv .venv
```
激活环境：
```powershell
.\.venv\Scripts\activate
```
激活后，终端应显示类似以下内容：
```powershell
(.venv) PS C:\Eli_Projects\databricks-mcp>
```
### 3. 安装依赖项
```powershell
pip install mcp requests python-dotenv
```
可选：创建 `requirements.txt` 文件：
```powershell
pip freeze > requirements.txt
```
然后，未来用户可以使用：
```powershell
pip install -r requirements.txt
```
## Databricks 身份验证
在项目根目录下创建 `.env` 文件：
```powershell
notepad .env
```
添加以下内容：
```env
DATABRICKS_HOST=https://your-workspace.azuredatabricks.net
DATABRICKS_TOKEN=your_databricks_personal_access_token
```
主机格式示例：
```env
DATABRICKS_HOST=https://adb-xxxxxxxxxxxxxxxx.x.azuredatabricks.net
```
不要分享或提交您的 Databricks 令牌。
## `.env.example` 示例
创建 `.env.example` 以便其他人了解所需变量：
```env
DATABRICKS_HOST=https://your-workspace.azuredatabricks.net
DATABRICKS_TOKEN=your_databricks_personal_access_token
```
## 测试 Databricks 连接
由于 MCP 服务器通过 JSON-RPC 通信，直接运行 `python server.py` 可能看起来像是在等待输入。为了进行快速的 Databricks API 自测试，请暂时替换 `server.py` 底部的内容：
```python
if __name__ == "__main__":
mcp.run()
```
为：
```python
if __name__ == "__main__":
if os.getenv("MCP_SELF_TEST") == "1":
print(summarize_workspace_start("/Workspace"))
else:
mcp.run()
```
然后运行：
```powershell
$env:MCP_SELF_TEST="1"
python server.py
```
预期输出形状：
```text
{'path': '/Workspace', 'count': 3, 'items': [...]}
```
测试后，重置变量：
```powershell
Remove-Item Env:\MCP_SELF_TEST
```
然后将 `server.py` 底部的内容更改回：
```python
if __name__ == "__main__":
mcp.run()
```
## Claude Desktop 配置
打开 Claude Desktop 配置文件。
Windows 位置：
```text
C:\Users\<YourUserName>\AppData\Roaming\Claude\claude_desktop_config.json
```
此项目路径的示例：
```json
{
"mcpServers": {
"databricks-workspace": {
"command": "C:\\Eli_Projects\\databricks-mcp\\.venv\\Scripts\\python.exe",
"args": [
"C:\\Eli_Projects\\databricks-mcp\\server.py"
]
}
}
}
```
如果您已经配置了其他 MCP 服务器，请在现有的 `mcpServers` 对象内添加 `databricks-workspace`。
另一个现有服务器的示例：
```json
{
"mcpServers": {
"databricks-genie": {
"command": "cmd",
"args": [
"/c",
"npx",
"mcp-remote",
"https://your-workspace.azuredatabricks.net/api/2.0/mcp/genie",
"--header",
"Authorization: Bearer your_databricks_token"
]
},
"databricks-workspace": {
"command": "C:\\Eli_Projects\\databricks-mcp\\.venv\\Scripts\\python.exe",
"args": [
"C:\\Eli_Projects\\databricks-mcp\\server.py"
]
}
}
}
```
编辑配置后：
1. 保存 `claude_desktop_config.json`。
2. 完全关闭 Claude Desktop。
3. 打开任务管理器并结束任何剩余的 Claude 进程。
4. 再次启动 Claude Desktop。
5. 进入 `设置 -> 开发者 -> 本地 MCP 服务器`。
6. 确认 `databricks-workspace` 正在运行。
## Claude 提示示例
MCP 服务器运行后，询问 Claude：
```text
使用 databricks-workspace 汇总我的 Databricks 工作区从 /Workspace。
```
```text
使用 databricks-workspace 列出 /Workspace/Users。
```
```text
使用 databricks-workspace 列出我的 Databricks 作业和最近的作业运行。
```
```text
使用 databricks-workspace 列出我的 Databricks 集群。
```
```text
使用 databricks-workspace 导出此笔记本并汇总代码：/Workspace/Users/example@example.com/my_notebook
```
## GitHub 设置
### 1. 创建 `.gitignore`
创建 `.gitignore`：
```powershell
notepad .gitignore
```
添加：
```gitignore
.venv/
.env
__pycache__/
*.pyc
.mypy_cache/
.pytest_cache/
.DS_Store
```
### 2. 初始化 Git
```powershell
git init
git status
```
确保 `.env` 未被暂存或提交。
### 3. 添加文件
```powershell
git add server.py README.md .gitignore .env.example
```
如果您创建了 `requirements.txt`，也请添加它：
```powershell
git add requirements.txt
```
### 4. 提交
```powershell
git commit -m "初始自定义 Databricks MCP 服务器"
```
### 5. 创建 GitHub 仓库
创建一个新的空 GitHub 仓库，例如：
```text
databricks-mcp-server
```
如果您已经在本地创建了 README、`.gitignore` 或许可证，请不要在 GitHub 上初始化仓库。
然后连接本地仓库：
```powershell
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/databricks-mcp-server.git
git push -u origin main
```
用您的 GitHub 用户名替换 `YOUR_USERNAME`。
## 安全注意事项
* 不要提交 `.env`。
* 不要提交 Databricks 令牌。
* 使用具有最低所需权限的 Databricks 令牌。
* 仅以只读工具启动。
* 除非您明确需要，否则不要添加用于删除、导入、运行作业、修改权限或终止集群的工具。
* 如果令牌在日志、截图或 GitHub 中暴露，请立即撤销并创建一个新的令牌。
## 限制
* 此服务器仅公开 `server.py` 中实现的工具。
* 它不自动理解除非添加相关 API 调用，否则不理解每个 Databricks 资产。
* 除非调用 `export_notebook` 并指定特定的笔记本路径，否则它不检查笔记本代码。
* 它不替换 Databricks Genie。Genie 仍然适用于配置的数据空间上的自然语言问题。
* 它旨在作为本地开发和学习项目，而不是生产服务。
## 可能的未来改进
* 为大型工作区和作业列表添加分页支持
* 添加递归工作区扫描器
* 添加笔记本汇总助手
* 添加 SQL 仓库列表
* 添加 Unity Catalog 元数据列表
* 添加对 Databricks 仓库的支持
* 添加结构化错误消息
* 添加不暴露机密的日志记录
* 添加测试
* 添加 Docker 支持
## 许可证
该项目可以在 MIT 许可证或您选择的另一个许可证下获得许可。
