MCP 数据处理服务器
项目介绍
Databricks MCP Server
动机
Databricks Unity Catalog (UC) 允许对您的数据资产进行详细的文档记录，包括目录、模式、表和列。彻底记录这些资产需要投入时间。一个常见的问题是：这种详细元数据条目的实际好处是什么？
这个MCP服务器提供了这一努力的强大理由。它使大型语言模型（LLMs）能够直接访问并利用这种Unity Catalog元数据。您在UC中描述的数据越全面，LLM代理就越能理解您的Databricks环境。这种更深层次的理解对于代理自主构建更智能和准确的SQL查询以满足数据请求至关重要。
概述
此模型上下文协议（MCP）服务器旨在与Databricks交互，重点在于利用Unity Catalog（UC）元数据，并实现全面的数据血缘探索。主要目标是为AI代理提供一套全面的工具，使其能够在没有人为干预的情况下独立回答关于数据的问题。通过自主探索UC，理解数据结构，分析数据血缘（包括笔记本和作业依赖关系），并执行SQL查询，代理可以完成数据请求而无需每一步都直接的人类干预。
除了传统的目录浏览之外，该服务器还使代理能够发现和分析实际处理您数据的代码。通过增强的血缘能力，代理可以识别读取或写入表的笔记本和作业，然后检查这些笔记本中实施的实际转换逻辑、业务规则和数据质量检查。这创建了一个强大的反馈循环，其中代理不仅了解“什么”数据存在，还了解“如何”处理和转换这些数据。
当以代理模式使用时，它可以成功地迭代多个请求以执行复杂任务，包括数据发现、影响分析和代码探索。
AI代理使用UC元数据的实际好处
此MCP服务器提供的工具旨在解析并呈现您添加到Unity Catalog中的描述，同时还可以深入探索您的数据处理代码。这对基于LLM的代理具有实际优势，直接影响其生成有用SQL和理解您的数据生态系统的能力：
- 更清晰的数据上下文：代理可以快速理解表和列的目的，减少歧义。这种基础理解是正确查询制定的第一步。
- 更精确的查询生成：访问描述、数据类型和关系帮助代理构造具有更高精度和语义正确的SQL查询。
- 用于查询规划的数据探索效率：元数据使代理能够更有效地导航目录和模式，允许它们确定应在SQL查询中包含的正确表和列。
- 全面的数据血缘：除了表到表的关系外，代理还可以发现处理数据的笔记本和作业，从而进行影响分析和调试数据管道问题。
- 代码级理解：通过笔记本内容探索，代理可以分析实际的转换逻辑、业务规则和数据质量检查，提供对数据处理和转换的更深入了解。
- 端到端数据流分析：代理可以从原始摄取追踪数据到最终消费，理解每个步骤的结构和处理逻辑。
在Unity Catalog中详细记录的元数据，通过此服务器访问，使LLM代理能够更好地操作信息并做出更有根据的决策，最终生成更有效的SQL查询。例如，模式描述有助于代理识别查询的相关数据源：
图1：Unity Catalog中的模式带有用户提供的描述。此MCP服务器使这些信息可以直接供LLM使用，指导其查询策略。
同样，列级别的详细注释澄清了每个字段的语义，这对于构建准确的SQL条件和选择至关重要：
图2：Unity Catalog中的列级别描述。这些细节传递给LLM，帮助其理解数据结构以进行精确的SQL生成。
可用工具和功能
此MCP服务器提供了一系列工具，旨在赋予与Databricks交互的LLM代理能力：
核心功能：
- 执行SQL查询：使用Databricks SDK通过
execute_sql_query(sql: str)工具运行任意SQL查询。这适用于有针对性的数据检索或复杂操作。 - 面向LLM的输出：所有描述性工具返回的信息都是Markdown格式，优化供大型语言模型消费，使代理更容易解析和理解上下文。
Unity Catalog探索工具：
服务器提供了以下工具来导航和理解您的Unity Catalog资产。这些工具设计为由LLM代理在构建查询或做决策之前收集上下文时使用。
-
list_uc_catalogs() -> str- 描述：列出所有可用的Unity Catalog及其名称、描述和类型。
- 何时使用：作为起点，当您不知道特定目录名称时，发现可用的数据源。它提供了工作区中所有可访问目录的高层次概述。
- 参数：无
-
describe_uc_catalog(catalog_name: str) -> str- 描述：提供特定Unity Catalog的摘要，列出其所有模式及其名称和描述。
- 何时使用：当您知道目录名称并且需要发现其中的模式时。这通常是描述特定模式或表的先决条件。
- 参数：
catalog_name：要描述的Unity Catalog的名称（例如，prod，dev，system）。
-
describe_uc_schema(catalog_name: str, schema_name: str, include_columns: Optional[bool] = False) -> str- 描述：提供特定Unity Catalog模式的详细信息。返回该模式中的所有表，可选地包括其列详情。
- 何时使用：为了理解模式的内容，主要是其表。设置
include_columns=True以获取列信息，这对于查询构建至关重要但会使输出变长。如果include_columns=False，则仅显示表名和描述，适合快速概览。 - 参数：
catalog_name：包含该模式的目录名称。schema_name：要描述的模式名称。include_columns：如果为True，则列出表及其列。默认为False，以获得更简洁的摘要。
-
describe_uc_table(full_table_name: str, include_lineage: Optional[bool] = False) -> str- 描述：提供特定Unity Catalog表的详细描述，具有全面的血缘能力。
- 何时使用：为了理解单个表的结构（列、数据类型、分区）。这是在对该表构建SQL查询之前必不可少的。可选地，它可以包括超越传统表到表依赖关系的全面血缘信息：
- 表血缘：上游表（该表从中读取的表）和下游表（从该表读取的表）
- 笔记本及作业血缘：读取或写入该表的笔记本，包括笔记本名称、工作区路径、关联的Databricks作业信息（作业名称、ID、任务详情）
- 代码发现：血缘提供笔记本路径，使代理能够直接读取当前仓库/工作区中的笔记本文件，允许分析实际的数据转换逻辑
- 参数：
full_table_name：表的完全限定三部分名称（例如，catalog.schema.table）。include_lineage：设置为True以获取全面的血缘（表、笔记本、作业）。默认为False。可能需要更长时间才能检索，但提供了丰富的上下文以理解数据依赖关系并启用代码探索。
-
execute_sql_query(sql: str) -> str- 注意：这是在“核心功能”下列出的同一工具，但在典型的代理工作流程中重复提及，涉及UC探索后进行查询。
- 描述：针对Databricks SQL仓库执行给定的SQL查询，并返回格式化的结果。
- 何时使用：当您需要运行特定的SQL查询时，如SELECT、SHOW或其他DQL语句。
- 参数：
sql：要执行的完整SQL查询字符串。
设置
系统需求
- Python 3.10+
- 如果计划通过
uv安装，请确保已安装
安装
- 安装所需的依赖项：
pip install -r requirements.txt
或者如果使用uv：
uv pip install -r requirements.txt
-
设置环境变量：
选项1：使用
.env文件（推荐）在该项目根目录下创建一个
.env文件，包含您的Databricks凭证：DATABRICKS_HOST="your-databricks-instance.cloud.databricks.com" DATABRICKS_TOKEN="your-databricks-personal-access-token" DATABRICKS_SQL_WAREHOUSE_ID="your-sql-warehouse-id"选项2：直接设置环境变量
export DATABRICKS_HOST="your-databricks-instance.cloud.databricks.com" export DATABRICKS_TOKEN="your-databricks-personal-access-token" export DATABRICKS_SQL_WAREHOUSE_ID="your-sql--warehouse-id"您可以在Databricks UI下的“SQL仓库”中找到SQL仓库ID。
DATABRICKS_SQL_WAREHOUSE_ID主要用于获取表血缘和通过execute_sql_query工具执行SQL查询。 元数据浏览工具（列出/描述目录、模式、表）使用Databricks SDK的一般UC API，并不严格需要SQL仓库ID，除非请求血缘。
权限需求
在使用此MCP服务器之前，请确保与DATABRICKS_TOKEN关联的身份（例如，用户或服务主体）具有必要的权限：
- Unity Catalog权限：
- 对要访问的目录具有
USE CATALOG权限。 - 对要访问的模式具有
USE SCHEMA权限。 - 对要查询或详细描述的表具有
SELECT权限（包括列信息）。 - 要列出所有目录，可能需要适当的元存储级别权限，或者它会列出用户至少具有
USE CATALOG权限的目录。
- 对要访问的目录具有
- SQL仓库权限（用于
execute_sql_query和血缘获取）：- 对指定的SQL仓库具有
CAN_USE权限，该仓库由DATABRICKS_SQL_WAREHOUSE_ID定义。
- 对指定的SQL仓库具有
- 令牌权限：
- 个人访问令牌或服务主体令牌应具有最小必要的范围。对于Unity Catalog操作，通常涉及工作区访问。对于SQL执行，涉及SQL权限。
- 强烈建议在生产或自动化场景中使用具有狭义定义权限的服务主体。
为了最佳的安全实践，请定期轮换您的访问令牌，并审核查询历史和UC审计日志以监控使用情况。
运行服务器
独立模式
要在独立模式下运行服务器（例如，用于测试与Agent Composer）：
python main.py
这将使用stdio传输启动MCP服务器，可用于Agent Composer或其他MCP客户端。
与Cursor一起使用
要将此MCP服务器与Cursor一起使用，在您的Cursor设置中配置它（~/.cursor/mcp.json）：
- 在您的主目录中创建一个
.cursor目录（如果尚不存在） - 创建或编辑该目录中的
mcp.json文件：
mkdir -p ~/.cursor
touch ~/.cursor/mcp.json
- 将以下配置添加到
mcp.json文件中，替换实际路径到您安装此服务器的位置：
{
"mcpServers": {
"databricks": {
"command": "uv",
"args": [
"--directory",
"/path/to/your/mcp-databricks-server",
"run",
"main.py"
]
}
}
}
示例使用python：
{
"mcpServers": {
"databricks": {
"command": "python",
"args": [
"/path/to/your/mcp-databricks-server/main.py"
]
}
}
}
重启Cursor以应用更改。然后可以在Cursor中使用databricks代理。
示例使用工作流（针对LLM代理）
此MCP服务器赋予LLM代理自主导航您的Databricks环境的能力。以下截图展示了典型交互，其中代理迭代地探索模式和表，即使初始查询未产生结果，也会调整其方法，直到成功检索所需数据。
图3：LLM代理使用Databricks MCP工具，展示迭代探索和查询细化以定位特定页面视图数据的过程。
代理可能会遵循以下工作流程：
- 发现可用目录：
list_uc_catalogs()- 代理决定从列表中
prod_catalog是相关的。
- 代理决定从列表中
- 探索特定目录：
describe_uc_catalog(catalog_name="prod_catalog")- 代理看到
sales_schema和inventory_schema。
- 代理看到
- 探索特定模式（快速查看）：
describe_uc_schema(catalog_name="prod_catalog", schema_name="sales_schema")- 代理看到表名如
orders，customers。
- 代理看到表名如
- 获取详细表结构（包括查询构建的列）：
describe_uc_schema(catalog_name="prod_catalog", schema_name="sales_schema", include_columns=True)- 或者，如果对特定表感兴趣：
describe_uc_table(full_table_name="prod_catalog.sales_schema.orders")
- 或者，如果对特定表感兴趣：
- 分析数据血缘并发现处理代码：
describe_uc_table(full_table_name="prod_catalog.sales_schema.orders", include_lineage=True)- 代理发现上游表、下游依赖关系以及处理此数据的笔记本
- 例如，看到
/Repos/production/etl/sales_processing.py写入此表
- 检查数据转换逻辑：代理直接读取IDE/仓库中的笔记本文件
/Repos/production/etl/sales_processing.py- 代理分析实际的Python/SQL代码以理解业务规则、数据质量检查和转换逻辑
- 构建并执行查询：
execute_sql_query(sql="SELECT customer_id, order_date, SUM(order_total) FROM prod_catalog.sales_schema.orders WHERE order_date > '2023-01-01' GROUP BY customer_id, order_date ORDER BY order_date DESC LIMIT 100")
使用Terraform管理元数据作为代码
虽然手动通过Databricks UI输入元数据是一个选项，但更强大和可扩展的方法是将您的Unity Catalog元数据定义为代码。像Terraform这样的工具允许您声明式地管理您的数据治理对象，包括目录和模式。这带来了几个优点：
- 版本控制：您的元数据定义可以存储在Git中，跟踪并与您的其他基础设施代码一起版本化。
- 可重复性和一致性：确保跨环境（开发、暂存、生产）的一致元数据。
- 自动化：将元数据管理集成到您的CI/CD管道中。
- 核心资产的维护更简单：尽管由于其动态性质，定义每个新表作为代码可能很复杂，但核心资产如目录和模式通常更加稳定，因此受益于这种方法。维护它们的定义和注释作为代码确保了您的数据景观有一个持久且文档齐全的基础。
这里是如何使用Terraform定义目录及其模式的示例：
resource "databricks_catalog" "prod_catalog" {
name = "prod"
comment = "企业所有数据的主要生产目录。"
storage_root = var.default_catalog_storage_root
force_destroy = false
}
# 'prod'目录内的模式
resource "databricks_schema" "prod_raw" {
catalog_name = databricks_catalog.prod_catalog.name
name = "raw"
comment = "所有不同项目的原始数据，包括遥测、游戏数据等，在任何转换之前。没有模式强制。"
}
resource "databricks_schema" "prod_bi_conformed" {
catalog_name = databricks_catalog.prod_catalog.name
name = "bi_conformed"
comment = "BI（银色）模式，清理并格式良好。模式强制。"
}
resource "databricks_schema" "prod_bi_modeled" {
catalog_name = databricks_catalog.prod_catalog.name
name = "bi_modeled"
comment = "BI（金色）模式，聚合并准备好消费。模式强制。"
}
如果您已经拥有现有的Unity Catalog目录和模式，不必重新创建它们就可以管理其元数据作为代码。Terraform提供了terraform import命令，允许您将现有基础设施（包括Unity Catalog资产）纳入其管理之下。一旦导入，您可以在Terraform配置中定义资源，并选择性地更新属性，如comment字段，而不会影响资产本身。例如，在导入现有模式后，您可以在.tf文件中添加或更新其comment，terraform apply只会应用这一更改。
采用元数据作为代码策略，特别是对于基础元素如目录和模式，极大地提高了此MCP服务器所依赖的元数据的质量和可靠性。反过来，这进一步提高了与您的Databricks数据交互的AI代理的有效性。
有关使用Terraform与Databricks Unity Catalog的更多详细信息，请参阅官方文档：