架构概述
┌─────────────┐ MCP Protocol ┌──────────────────┐ OAuth ┌─────────────────┐
│ Claude │ ◄─────────────────────► │ dba-mcp-proxy │ ◄──────────────────► │ Databricks App │
│ CLI │ (stdio/JSON-RPC) │ (local process) │ (HTTPS/SSE) │ (MCP Server) │
└─────────────┘ └──────────────────┘ └─────────────────┘
▲ │
│ ▼
└────────── Databricks OAuth ──────► Workspace APIsDatabricks MCP 服务器
在Databricks应用程序中，主机模型上下文协议（MCP）提供了提示和工具，使像Claude这样的AI助手能够与您的Databricks工作区进行交互。
这是什么？
此模板允许您在Databricks应用程序上创建一个MCP服务器。您可以：
- 添加提示 作为简单的Markdown文件在
prompts/文件夹 - 创建工具 作为利用Databricks SDK的Python函数
连接Claude与您的Databricks工作区的桥梁——您定义Claude能看到和能做什么，其余的由这个服务器处理。
组件
- MCP服务器 (
server/app.py一个集成了MCP服务器的FastAPI应用，该应用：
- 动态加载来自（某处）的提示 prompts/*.md 文件 - 通过（某种方式）将Python函数作为MCP工具暴露出来 @mcp_server.tool 装饰器 - 处理通过服务器发送事件（Server-Sent Events）的HTTP请求和MCP协议
- 提示 （
prompts/): 简单的Markdown文件，其中：
- 文件名 = 提示名称（例如。， check_system.md → check_system 提示) - 第一行以……开头 # = 描述 - 文件内容 = 返回给Claude的内容
- 本地代理 (
dba_mcp_proxy/): 验证并代理MCP请求：
- 自动处理Databricks OAuth身份验证 - 在克劳德的stdin协议与HTTP/SSE之间进行翻译转换 - 适用于本地开发和已部署的应用程序
先决条件
- Claude CLI（命令行界面）
- 订阅Databricks应用程序
- python
本地开发
# Clone and setup
git clone
cd
./setup.sh
# Start dev server
./watch.sh
# Set your configuration for local testing
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_APP_URL="http://localhost:8000" # Local dev server
# Add to Claude for local testing
claude mcp add databricks-mcp-local --scope local -- \
uvx --from git+ssh://git@github.com/YOUR-ORG/YOUR-REPO.git dba-mcp-proxy \
--databricks-host $DATABRICKS_HOST \
--databricks-app-url $DATABRICKS_APP_URL
## Customization Guide
This template uses [FastMCP](https://github.com/jlowin/fastmcp), a framework that makes it easy to build MCP servers. FastMCP provides two main decorators for extending functionality:
- **`@mcp_server.prompt`** - For registering prompts that return text
- **`@mcp_server.tool`** - For registering tools that execute functions
### Adding Prompts
The easiest way is to create a markdown file in the `prompts/` directory:
Get cluster information
List all available clusters in the workspace with their current status
提示将自动加载以下内容：
- **名字**文件名（不含扩展名）（例如。， `get_clusters.md` → `get_clusters`）
- **描述**在（某处）之后的第一行 `#`
- **内容**整个文件内容
或者，您可以将提示注册为函数在 `server/app.py`：
@mcp_server.prompt(name="dynamic_status", description="Get dynamic system status") async def get_dynamic_status(): # This can include dynamic logic, API calls, etc. w = get_workspace_client() current_user = w.current_user.me() return f"Current user: {current_user.display_name}\nWorkspace: {DATABRICKS_HOST}"
我们自动加载 `prompts/` 为了方便起见，但当你需要动态内容时，基于功能的提示非常有用。
### 添加工具
在（某处）添加一个函数 `server/app.py` 使用 `@mcp_server.tool` 装饰器：
@mcp_server.tool def list_clusters(status: str = "RUNNING") -> dict: """List Databricks clusters by status.""" w = get_workspace_client() clusters = [] for cluster in w.clusters.list(): if cluster.state.name == status: clusters.append({ "id": cluster.cluster_id, "name": cluster.cluster_name, "state": cluster.state.name }) return {"clusters": clusters}
工具必须：
- 使用 `@mcp_server.tool` 装饰器
- 具有文档字符串（成为工具描述）
- 返回可序列化的JSON数据（字典、列表、字符串等）
- 只接受可序列化为JSON的参数
## 部署
Deploy to Databricks Apps
./deploy.sh
Check status and get your app URL
./app_status.sh
您的MCP服务器将在 `https://your-app.databricksapps.com/mcp/`
这个（或：那个，具体根据上下文确定） `app_status.sh` 脚本将显示您已部署的应用程序的URL，您将需要该URL用于 `DATABRICKS_APP_URL` 在将MCP服务器添加到Claude时设置环境变量。
## 认证
- **本地开发**无需认证
- **生产**代理会自动处理OAuth，使用您的Databricks CLI凭据
## 示例
### 与Claude一起使用
添加后，您可以在Claude中与您的MCP服务器进行交互：
Human: What prompts are available?
Claude: I can see the following prompts from your Databricks MCP server:
- check_system: Get system information
- list_files: List files in the current directory
- ping_google: Check network connectivity
### 样品工具使用
Human: Can you execute a SQL query to show databases?
Claude: I'll execute that SQL query for you using the execute_dbsql tool.
[Executes SQL and returns results]
## 项目结构
├── server/ # FastAPI backend with MCP server │ ├── app.py # Main application + MCP tools │ └── routers/ # API endpoints ├── prompts/ # MCP prompts (markdown files) │ ├── check_system.md │ ├── list_files.md │ └── ping_google.md ├── dba_mcp_proxy/ # MCP proxy for Claude CLI │ └── mcp_client.py # OAuth + proxy implementation ├── client/ # React frontend (optional) ├── scripts/ # Development tools └── pyproject.toml # Python package configuration
## 高级用法
### 环境变量
在（某处）进行配置 `.env.local`:
DATABRICKS_HOST=https://your-workspace.cloud.databricks.com DATABRICKS_TOKEN=your-token # For local development DATABRICKS_SQL_WAREHOUSE_ID=your-warehouse-id # For SQL tools
### 创建复杂工具
工具可以访问完整的Databricks软件开发工具包（SDK）：
@mcp_server.tool def create_job(name: str, notebook_path: str, cluster_id: str) -> dict: """Create a Databricks job.""" w = get_workspace_client() job = w.jobs.create( name=name, tasks=[{ "task_key": "main", "notebook_task": {"notebook_path": notebook_path}, "existing_cluster_id": cluster_id }] ) return {"job_id": job.job_id, "run_now_url": f"{DATABRICKS_HOST}/#job/{job.job_id}"}
## 测试您的MCP服务器
此模板包含全面的测试工具，用于在多个层面验证MCP（可能指某种系统或组件）的功能。
### 快速验证
在将MCP服务器添加到Claude后，验证其是否正常工作：
List available prompts and tools
echo "What MCP prompts are available from databricks-mcp?" | claude
Test a specific prompt
echo "Use the check_system prompt from databricks-mcp" | claude
### 全面测试套件
该（或：这个） `claude_scripts/` 该目录包含6种测试工具，用于全面验证MCP（多协议控制器）：
#### 命令行测试
Test local MCP server (requires ./watch.sh to be running)
./claude_scripts/test_local_mcp_curl.sh # Direct HTTP/curl tests with session handling ./claude_scripts/test_local_mcp_proxy.sh # MCP proxy client tests
Test remote MCP server (requires Databricks auth and deployment)
./claude_scripts/test_remote_mcp_curl.sh # OAuth + HTTP tests with dynamic URL discovery ./claude_scripts/test_remote_mcp_proxy.sh # Full end-to-end MCP proxy tests
#### 交互式网页用户界面测试
Launch MCP Inspector for visual testing (requires ./watch.sh for local)
./claude_scripts/inspect_local_mcp.sh # Local server web interface ./claude_scripts/inspect_remote_mcp.sh # Remote server web interface