数据湖MCP

Name: 数据湖MCP
Author: markov-kernel

作者：markov-kernel43 星标更新：2025-11-05

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

项目介绍

Databricks MCP 服务器

一个生产就绪的 模型上下文协议 (MCP) 服务器，它向兼容 MCP 的代理和工具暴露 Databricks REST 能力。版本 0.4.4 引入了结构化响应、资源缓存、重试感知网络以及端到端的弹性改进。

关键能力

结构化 MCP 响应 - 每个工具返回一个 CallToolResult，其中包含 content 中的人类可读摘要和符合工具 outputSchema 的机器可读负载 structuredContent。
资源缓存 - 大型笔记本/工作区导出仅缓存一次，并作为带有 URI 如 resource://databricks/exports/{id} 的 resource_link 内容块返回（为了方便，也在元数据中反映）。
进度与指标 - 长时间运行的操作流式传输 MCP 进度通知，并跟踪每个工具的成功/错误/超时/取消指标。
弹性的网络 - 共享 HTTP 客户端注入请求 ID，强制执行超时，并对可重试的 Databricks 响应（如 408/429/5xx）进行指数退避重试。
异步运行时 - 基于 mcp.server.FastMCP 构建，具有集中化的 JSON 日志记录和并发防护，以确保可预测的 stdio 行为。

架构亮点

databricks_mcp/server/databricks_mcp_server.py - 快速 MCP 服务器，具备工具注册、进度处理、指标和资源缓存。
databricks_mcp/core/utils.py - HTTP 工具，包括相关 ID、重试和错误映射到 DatabricksAPIError。
databricks_mcp/core/logging_utils.py - JSON 日志配置，用于 stderr 和文件输出。
databricks_mcp/core/models.py - Pydantic 模型（例如 ClusterConfig），由工具模式使用。
在 tests/ 下的测试模拟 Databricks API，验证编排、结构化响应和模式元数据，无需 shell 脚本。

要深入了解数据流和设计决策，请参阅 ARCHITECTURE.md。

安装

先决条件

Python 3.10+
使用 uv（https://github.com/astral-sh/uv）进行依赖管理和发布

快速安装（推荐）

使用以下深度链接注册服务器到 Cursor - 它解析为 uvx databricks-mcp-server@latest 并自动获取未来更新。

cursor://anysphere.cursor-deeplink/mcp/install?name=databricks-mcp&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJkYXRhYnJpY2tzLW1jcC1zZXJ2ZXIiXSwiZW52Ijp7IkRBVEFCUklDS1NfSE9TVCI6IiR7REFUQUJSSUNLU19IT1NUfSIsIkRBVEFCUklDS1NfVE9LRU4iOiIke0RBVEFCUklDS1NfVE9LRU59IiwiREFUQUJSSUNLU19XQVJFSE9VU0VfSUQiOiIke0RBVEFCUklDS1NfV0FSRUhPVVNFX0lEfSJ9fQ==

手动安装

# 克隆并进入仓库
git clone https://github.com/markov-kernel/databricks-mcp.git
cd databricks-mcp

# 创建隔离环境（可选但推荐）
uv venv
source .venv/bin/activate  # Linux/Mac
# .\.venv\Scripts\activate  # Windows PowerShell

# 安装包和开发依赖
uv pip install -e .
uv pip install -e ".[dev]"

配置

设置以下环境变量（或从 .env.example 填充 .env）。

export DATABRICKS_HOST="https://your-workspace.databricks.com"
export DATABRICKS_TOKEN="dapiXXXXXXXXXXXXXXXX"
export DATABRICKS_WAREHOUSE_ID="sql_warehouse_12345"  # 可选默认值
export TOOL_TIMEOUT_SECONDS=300
export MAX_CONCURRENT_REQUESTS=8
export HTTP_TIMEOUT_SECONDS=60
export API_MAX_RETRIES=3
export API_RETRY_BACKOFF_SECONDS=0.5

运行服务器

uvx databricks-mcp-server@latest

提示：追加 --refresh（例如 uvx databricks-mcp-server@latest --refresh）以在发布后强制 uv 解析最新的 PyPI 发布。日志以 JSON 行的形式输出到 stderr，并保存到工作目录中的 databricks_mcp.log 文件。

调整日志：

uvx databricks-mcp-server@latest -- --log-level DEBUG

与 MCP 客户端集成

Codex CLI (STDIO)

通过 CLI 注册服务器并注入凭据：

codex mcp add databricks   --env DATABRICKS_HOST="https://your-workspace.databricks.com"   --env DATABRICKS_TOKEN="dapi_XXXXXXXXXXXXXXXX"   --env DATABRICKS_WAREHOUSE_ID="sql_warehouse_12345"   -- uvx databricks-mcp-server@latest
# 发布后立即添加 --refresh 以使 uv 缓存失效

或者编辑 ~/.codex/config.toml：

[mcp_servers.databricks]
command = "uvx"
args    = ["databricks-mcp-server@latest"]
env = {
  DATABRICKS_HOST = "https://your-workspace.databricks.com",
  DATABRICKS_TOKEN = "dapi_XXXXXXXXXXXXXXXX",
  DATABRICKS_WAREHOUSE_ID = "sql_warehouse_12345"
}
startup_timeout_sec = 15
tool_timeout_sec    = 300

计划 HTTP 部署？Codex 还支持 url = "https://…" 加上 bearer_token_env_var = "DATABRICKS_TOKEN" 或 codex mcp login（带 experimental_use_rmcp_client = true）。

Cursor

{
  "mcpServers": {
    "databricks-mcp-local": {
      "command": "uvx",
      "args": ["databricks-mcp-server@latest"],
      "env": {
        "DATABRICKS_HOST": "https://your-workspace.databricks.com",
        "DATABRICKS_TOKEN": "dapiXXXXXXXXXXXXXXXX",
        "DATABRICKS_WAREHOUSE_ID": "sql_warehouse_12345",
        "RUNNING_VIA_CURSOR_MCP": "true"
      }
    }
  }
}

保存后重启 Cursor 并调用工具为 databricks-mcp-local:<tool>。

Claude CLI

claude mcp add databricks-mcp-local   -s user   -e DATABRICKS_HOST="https://your-workspace.databricks.com"   -e DATABRICKS_TOKEN="dapiXXXXXXXXXXXXXXXX"   -e DATABRICKS_WAREHOUSE_ID="sql_warehouse_12345"   -- uvx databricks-mcp-server@latest

处理工具响应

structuredContent 携带机器可读负载。大型工件作为 resource_link 内容块返回，使用类似 resource://databricks/exports/{id} 的 URI，并可通过 MCP 资源 API 获取。

result = await session.call_tool("list_clusters", {})
summary = next((block.text for block in result.content if getattr(block, "type", "") == "text"), "")
clusters = (result.structuredContent or {}).get("clusters", [])
resource_links = [block for block in result.content if isinstance(block, dict) and block.get("type") == "resource_link"]

进度通知遵循 MCP 的进度令牌机制；Codex 在工具运行时在 UI 中显示这些消息。

示例 - SQL 查询

result = await session.call_tool("execute_sql", {"statement": "SELECT * FROM samples LIMIT 10"})
print(result.content[0].text)
rows = (result.structuredContent or {}).get("result", [])

示例 - 工作区文件导出

result = await session.call_tool("get_workspace_file_content", {
    "path": "/Users/user@domain.com/report.ipynb",
    "format": "SOURCE"
})
resource_link = next((block for block in result.content if isinstance(block, dict) and block.get("type") == "resource_link"), None)
if resource_link:
    contents = await session.read_resource(resource_link["uri"])

可用工具

类别	工具	描述
集群	`list_clusters`, `create_cluster`, `terminate_cluster`, `get_cluster`, `start_cluster`, `resize_cluster`, `restart_cluster`	管理交互式集群
作业	`list_jobs`, `create_job`, `delete_job`, `run_job`, `run_notebook`, `sync_repo_and_run_notebook`, `get_run_status`, `list_job_runs`, `cancel_run`	管理计划和临时作业
工作区	`list_notebooks`, `export_notebook`, `import_notebook`, `delete_workspace_object`, `get_workspace_file_content`, `get_workspace_file_info`	检查和管理工作区资产
DBFS	`list_files`, `dbfs_put`, `dbfs_delete`	探索 DBFS 并管理文件
SQL	`execute_sql`	提交 SQL 语句，可选 `warehouse_id`, `catalog`, `schema_name`
库	`install_library`, `uninstall_library`, `list_cluster_libraries`	管理集群库
存储库	`create_repo`, `update_repo`, `list_repos`, `pull_repo`	管理 Databricks 存储库
Unity Catalog	`list_catalogs`, `create_catalog`, `list_schemas`, `create_schema`, `list_tables`, `create_table`, `get_table_lineage`	Unity Catalog 操作

开发工作流

uv run black databricks_mcp tests
uv run pylint databricks_mcp tests
uv run pytest
uv build
uv publish --token "$PYPI_TOKEN"

测试

uv run pytest

Pytest 套件模拟 Databricks API，提供确定性的结构化输出和转录测试。

发布构建

确保 PYPI_TOKEN 可用（通过 .env 或环境变量）后再发布：

uv build
uv publish --token "$PYPI_TOKEN"

支持与联系

维护者：Olivier Debeuf De Rijcker (olivier@markov.bot)
问题：GitHub Issues
架构深入：ARCHITECTURE.md

许可

根据 MIT 许可证发布。详见 LICENSE。