XiYan MCP Server：让数据库开口说话

当老板问"上个月华北区域卖得最好的产品是什么"时……

这不是一道语文题，而是一道 SQL 题。

对于大多数业务人员来说，数据库是一个黑盒子——他们知道数据在里面，却无法直接触达。传统的解决方案要么依赖工程师写查询语句，要么借助 BI 工具预先配置报表。两种方式都有明显短板：前者响应慢，后者缺乏灵活性。

XiYan MCP Server 带来了一种全新的可能——用自然语言直接查询数据库。你只需要对 AI 说"查一下华北区域上个月卖得最好的产品"，它就会自动理解你的意图，生成正确的 SQL 语句，连接数据库执行查询，并返回结果。整个过程不需要写一行代码，不需要打开任何数据库客户端。

背景：Text-to-SQL 的技术演进与 XiYan-SQL 的 SOTA 之路

Text-to-SQL（自然语言转 SQL）并不是一个新问题，但长期以来，主流方案要么依赖闭源大模型的强大推理能力，要么使用精调小模型但效果平庸。两者的核心矛盾在于：精度与成本的取舍。

XGenerationLab 团队（作者 Zhiling Luo，来自阿里巴巴）提出的 XiYan-SQL 框架另辟蹊径，采用多生成器集成（Multi-Generator Ensemble）策略。简单来说，就是让多个不同能力的模型各自生成候选 SQL，再通过评审机制选出最优结果。这听起来类似"思维链"（Chain-of-Thought），但 XiYan-SQL 在生成-评审流程上做了大量针对 SQL 语法的专项优化，包括方言感知、多表 JOIN 处理、聚合函数理解等。

其核心模型 XiYanSQL-QwenCoder-32B 在 Text-to-SQL 领域最具挑战性的 BIRD 基准测试上达到了 EX 得分 69.03%，刷新了单一模型（single model）的 SOTA 记录。更值得注意的是，2025 年 10 月发布的 XiYan-SQL-CRITIC 版本在 BIRD-CRITIC-PG 基准上更进一步，达到了 44.53% Pass Rate，稳居榜首。团队还将模型尺寸下探至 3B、7B、14B、32B 四个版本，覆盖从个人笔记本到服务器集群的不同算力场景。

为什么 BIRD 基准值得关注？ BIRD（Big Bench for Large-scale Database grounded Text-to-SQL）由香港科技大学等机构发布，是目前最难、最接近真实业务场景的 Text-to-SQL 评测集。相比 Spider 等经典数据集，BIRD 的查询更复杂、涉及数据库规模更大、对方言和上下文理解的要求更高。能在 BIRD 上取得好成绩，意味着在实际企业数据库场景中同样可靠。

XiYan MCPBench 评测 图2：MCPBench 基准测试结果，XiYan MCP Server 在 MySQL 和 PostgreSQL 两个赛道均显著领先同类 MCP Server

核心技术：MCP 协议 + Text-to-SQL 的化学反应

MCP 协议：AI 工具的"USB-C"标准

Model Context Protocol（MCP） 是 Anthropic 在 2024 年底推出的开放协议，旨在为 AI 助手与外部工具之间建立标准化的通信规范。它的设计理念与 USB-C 类似——无论是什么品牌的设备，只要支持 USB-C，就能互联互通。同理，无论你用 Claude Desktop、Cursor、Witsy、Goose 还是 Cline，只要它们支持 MCP，就能接入 XiYan MCP Server。

MCP 协议定义了三类标准接口：

Tools（工具）：AI 可主动调用的函数，get_data 是 XiYan MCP 的核心工具
Resources（资源）：AI 可读取的静态数据，如数据库 schema、表结构
Prompts（提示）：预定义的提示模板

get_data 工具：自然语言 → SQL → 查询结果

当你向 AI 提问时，XiYan MCP Server 的工作流程如下：

接收自然语言查询："北京区域 Q1 销售额超过 100 万的客户有哪些？"
获取数据库 Schema：通过 MCP Resource 接口读取目标数据库的表结构（列名、数据类型、外键关系）
调用 XiYan-SQL 模型：将自然语言 + Schema 组合成 Prompt，送给 Text-to-SQL 模型
生成并执行 SQL：生成的 SQL 经过安全校验后，在数据库中执行
返回结构化结果：以 MCP 标准的 TextContent 格式返回查询结果

代码层面，整个流程在 server.py 中通过 FastMCP 框架实现，使用 @mcp.tool() 装饰器注册 get_data 函数，并通过 sqlalchemy + mysql-connector-python 连接数据库。

双模式部署：云端 vs 本地

XiYan MCP Server 支持两种 LLM 接入模式：

模式	LLM 来源	速度	安全性	配置难度
远程模式	Modelscope / Dashscope / OpenAI API	快（毫秒级）	依赖网络	低
本地模式	XiYanSQL-QwenCoder-3B (GGUF量化)	较慢（~12秒/查询）	最高（数据不出本机）	中

本地模式特别适合对数据隐私有严格要求的场景——金融、医疗、法律等行业的数据合规要求极高，不允许上传到第三方 API。本地模式下，整个推理链路完全在本地运行，数据库连接也是直连本地实例，数据不流出任何边界。

代码架构：清晰的模块分层

XiYan MCP Server 的代码结构简洁，总共约 3000 行 Python 代码，采用经典的模块化分层设计：

src/xiyan_mcp_server/
├── server.py              # MCP 服务入口，FastMCP 实例注册
├── __main__.py            # CLI 入口点
├── config_demo.yml        # 默认配置文件
├── database_env.py        # 数据库环境变量
├── local_model/
│   ├── llama_cpp_server.py    # Llama.cpp 本地推理服务
│   └── local_xiyan_server.py  # 本地 XiYan 模型服务（Modelscope SDK）
└── utils/
    ├── db_config.py       # 数据库配置封装（SQLAlchemy）
    ├── db_source.py       # HITLSQLDatabase 数据库交互封装
    ├── db_util.py         # 数据库连接初始化
    ├── db_mschema.py      # mSchema（Meta-Schema）数据库元信息提取
    ├── llm_util.py        # LLM API 调用封装（OpenAI SDK 兼容）
    ├── file_util.py       # 文件工具（Qwen 模型输出解析）
    ├── logger_util.py     # 日志工具
    └── common_util.py     # 通用工具函数

核心依赖栈：FastMCP >= 1.0.0 → sqlalchemy → mysql-connector-python / pymysql，底层 LLM 调用使用 OpenAI 兼容的 openai Python SDK，支持 Modelscope、Dashscope、OpenAI 等多种后端。

mSchema 设计：这是 XiYan-SQL 论文提出的核心概念。与传统 DDL（Data Definition Language）相比，mSchema 对数据库元信息做了更高层次的抽象，包含表间关系、语义标签、示例数据等补充信息，帮助 Text-to-SQL 模型更准确地理解数据库结构。

容器化：pip 和 Docker 双路径

项目提供了两种安装方式：

# 方式一：pip 一键安装（推荐）
pip install xiyan-mcp-server

# 方式二：Docker 容器化
docker build -t xiyan-mcp .
docker run -v ./config.yml:/app/config.yml xiyan-mcp

Dockerfile 采用了单阶段构建，基于 python:3.11-slim，镜像体积约 1.2GB。没有提供 docker-compose.yml，需要自行管理数据库容器与 MCP Server 之间的网络连接。

XiYan Logo 图4：XiYan 项目官方 Logo

上手体验：30 分钟跑通全流程

环境准备

项目要求 Python 3.11+，这一点需要注意——很多企业内网仍在使用 Python 3.8/3.9，升级环境可能需要额外步骤。

基础依赖（pip 安装）：

pip install xiyan-mcp-server

配置文件（config_demo.yml）：

mcp:
  transport: "stdio"   # stdio（Claude Desktop 等）/ sse（Web 服务）
model:
  name: "XGenerationLab/XiYanSQL-QwenCoder-32B-2412"
  key: "your-modelscope-key"   # Modelscope API Key
  url: "https://api-inference.modelscope.cn/v1/"
database:
  host: "localhost"
  port: 3306
  user: "root"
  password: "your-db-password"
  database: "your_database_name"

Claude Desktop 配置示例

在 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "xiyan": {
      "command": "python",
      "args": ["-m", "xiyan_mcp_server"],
      "env": {
        "YML": "/absolute/path/to/your/config.yml"
      }
    }
  }
}

重启 Claude Desktop 后，在对话中直接提问："帮我查一下 2025 年 6 月销售额 TOP5 的产品"，即可得到结果。

Goose 集成 图5：Goose AI Agent 集成 XiYan MCP Server 效果

现有限制与风险

项目在 GitHub Issues 中也公开承认了一些局限性，用户在选型时需要充分评估：

1. 本地模式速度瓶颈

本地模式下（Llama.cpp 量化推理），在 MacBook M3 上单次查询约需 12 秒。对于需要实时交互的业务场景，这个延迟难以接受。云端模式虽然快（毫秒级），但需要数据经过第三方 API。

2. 仅支持 MySQL 和 PostgreSQL

暂不支持 SQLite、Oracle、SQL Server 等其他主流数据库。对于已有 Oracle 或 SQL Server 资产的企业，需要额外的数据同步成本。

3. SQL 注入风险

虽然代码中有 SQL 校验逻辑，但生成的 SQL 是直接执行的，任何模型幻觉导致的错误 SQL 都可能对生产数据库造成影响。建议在非生产环境先验证查询语句，或使用只读数据库账号。

4. 多表复杂 JOIN 仍有局限

从 BIRD-CRITIC 评测结果看，最难的查询（如跨 5 张表的聚合查询）仍有一定失败率。对于 BI 报表场景，建议用户先用自然语言描述简单查询，逐步增加复杂度。

5. Schema 变更感知弱

当数据库表结构发生变化（新增列、修改类型）时，XiYan MCP Server 需要重启才能更新 mSchema cache。如果数据库高频变更（如互联网公司的快速迭代场景），需要自动化 schema 同步机制。

行业意义：从"能用"到"好用"的跨越

XiYan MCP Server 的出现，反映了 AI 数据库交互领域的一个趋势：从封闭的 BI 工具向开放的 AI Agent 生态迁移。

传统 BI 工具（如 Tableau、PowerBI）需要专业的数据建模和报表设计，成本高昂且迭代缓慢。而基于 MCP 的自然语言查询方案，将数据访问能力下沉到日常对话层级，任何懂业务的员工都能直接获取数据洞察。这不仅仅是效率提升，更是数据民主化的体现。

Contextual AI 在 2025 年的一篇博客中也专门提到了 XiYan-SQL 的 mSchema 设计，认为其"上下文增强"策略在本地模型的 Text-to-SQL 任务中起到了关键作用。这说明 XiYan-SQL 不仅在实际应用中有价值，其设计思路也被学术社区所认可。

总结

XiYan MCP Server 是一款将 SOTA Text-to-SQL 能力与 MCP 协议深度融合的中间件产品。它的核心价值在于：

让非技术人员用自然语言直接查询数据库，打破数据获取的瓶颈
基于 XiYan-SQL 多生成器集成框架，在 BIRD 等权威基准上保持 SOTA
支持 远程/本地双模式，兼顾速度与数据安全
零代码集成 Claude Desktop / Cursor / Goose / Cline 等主流 AI 工具

适合场景：企业内部数据分析小工具、BI 系统自然语言增强、数据库管理员辅助工具、数据合规要求高的本地部署场景。

部署难度中等——pip 安装简单，但需要配置数据库连接和 LLM API 凭证。容器化支持有 Dockerfile，但缺乏 docker-compose 一键编排。整体推荐给有 Python 和数据库基础的团队使用。

本报告基于 GitHub 公开信息及官方文档生成，分析时间：2026-07-10

XiYan MCP Server：让数据库开口说话

当老板问"上个月华北区域卖得最好的产品是什么"时……

这不是一道语文题，而是一道 SQL 题。

背景：Text-to-SQL 的技术演进与 XiYan-SQL 的 SOTA 之路

为什么 BIRD 基准值得关注？ BIRD（Big Bench for Large-scale Database grounded Text-to-SQL）由香港科技大学等机构发布，是目前最难、最接近真实业务场景的 Text-to-SQL 评测集。相比 Spider 等经典数据集，BIRD 的查询更复杂、涉及数据库规模更大、对方言和上下文理解的要求更高。能在 BIRD 上取得好成绩，意味着在实际企业数据库场景中同样可靠。

XiYan MCPBench 评测 图2：MCPBench 基准测试结果，XiYan MCP Server 在 MySQL 和 PostgreSQL 两个赛道均显著领先同类 MCP Server

核心技术：MCP 协议 + Text-to-SQL 的化学反应

MCP 协议：AI 工具的"USB-C"标准

MCP 协议定义了三类标准接口：

Tools（工具）：AI 可主动调用的函数，get_data 是 XiYan MCP 的核心工具
Resources（资源）：AI 可读取的静态数据，如数据库 schema、表结构
Prompts（提示）：预定义的提示模板

get_data 工具：自然语言 → SQL → 查询结果

当你向 AI 提问时，XiYan MCP Server 的工作流程如下：

接收自然语言查询："北京区域 Q1 销售额超过 100 万的客户有哪些？"
获取数据库 Schema：通过 MCP Resource 接口读取目标数据库的表结构（列名、数据类型、外键关系）
调用 XiYan-SQL 模型：将自然语言 + Schema 组合成 Prompt，送给 Text-to-SQL 模型
生成并执行 SQL：生成的 SQL 经过安全校验后，在数据库中执行
返回结构化结果：以 MCP 标准的 TextContent 格式返回查询结果

双模式部署：云端 vs 本地

XiYan MCP Server 支持两种 LLM 接入模式：

模式	LLM 来源	速度	安全性	配置难度
远程模式	Modelscope / Dashscope / OpenAI API	快（毫秒级）	依赖网络	低
本地模式	XiYanSQL-QwenCoder-3B (GGUF量化)	较慢（~12秒/查询）	最高（数据不出本机）	中

代码架构：清晰的模块分层

XiYan MCP Server 的代码结构简洁，总共约 3000 行 Python 代码，采用经典的模块化分层设计：

src/xiyan_mcp_server/
├── server.py              # MCP 服务入口，FastMCP 实例注册
├── __main__.py            # CLI 入口点
├── config_demo.yml        # 默认配置文件
├── database_env.py        # 数据库环境变量
├── local_model/
│   ├── llama_cpp_server.py    # Llama.cpp 本地推理服务
│   └── local_xiyan_server.py  # 本地 XiYan 模型服务（Modelscope SDK）
└── utils/
    ├── db_config.py       # 数据库配置封装（SQLAlchemy）
    ├── db_source.py       # HITLSQLDatabase 数据库交互封装
    ├── db_util.py         # 数据库连接初始化
    ├── db_mschema.py      # mSchema（Meta-Schema）数据库元信息提取
    ├── llm_util.py        # LLM API 调用封装（OpenAI SDK 兼容）
    ├── file_util.py       # 文件工具（Qwen 模型输出解析）
    ├── logger_util.py     # 日志工具
    └── common_util.py     # 通用工具函数

容器化：pip 和 Docker 双路径

项目提供了两种安装方式：

# 方式一：pip 一键安装（推荐）
pip install xiyan-mcp-server

# 方式二：Docker 容器化
docker build -t xiyan-mcp .
docker run -v ./config.yml:/app/config.yml xiyan-mcp

Dockerfile 采用了单阶段构建，基于 python:3.11-slim，镜像体积约 1.2GB。没有提供 docker-compose.yml，需要自行管理数据库容器与 MCP Server 之间的网络连接。

XiYan Logo 图4：XiYan 项目官方 Logo

上手体验：30 分钟跑通全流程

环境准备

项目要求 Python 3.11+，这一点需要注意——很多企业内网仍在使用 Python 3.8/3.9，升级环境可能需要额外步骤。

基础依赖（pip 安装）：

pip install xiyan-mcp-server

配置文件（config_demo.yml）：

mcp:
  transport: "stdio"   # stdio（Claude Desktop 等）/ sse（Web 服务）
model:
  name: "XGenerationLab/XiYanSQL-QwenCoder-32B-2412"
  key: "your-modelscope-key"   # Modelscope API Key
  url: "https://api-inference.modelscope.cn/v1/"
database:
  host: "localhost"
  port: 3306
  user: "root"
  password: "your-db-password"
  database: "your_database_name"

Claude Desktop 配置示例

在 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "xiyan": {
      "command": "python",
      "args": ["-m", "xiyan_mcp_server"],
      "env": {
        "YML": "/absolute/path/to/your/config.yml"
      }
    }
  }
}

重启 Claude Desktop 后，在对话中直接提问："帮我查一下 2025 年 6 月销售额 TOP5 的产品"，即可得到结果。

Goose 集成 图5：Goose AI Agent 集成 XiYan MCP Server 效果

现有限制与风险

项目在 GitHub Issues 中也公开承认了一些局限性，用户在选型时需要充分评估：

1. 本地模式速度瓶颈

2. 仅支持 MySQL 和 PostgreSQL

暂不支持 SQLite、Oracle、SQL Server 等其他主流数据库。对于已有 Oracle 或 SQL Server 资产的企业，需要额外的数据同步成本。

3. SQL 注入风险

4. 多表复杂 JOIN 仍有局限

5. Schema 变更感知弱

行业意义：从"能用"到"好用"的跨越

XiYan MCP Server 的出现，反映了 AI 数据库交互领域的一个趋势：从封闭的 BI 工具向开放的 AI Agent 生态迁移。

总结

XiYan MCP Server 是一款将 SOTA Text-to-SQL 能力与 MCP 协议深度融合的中间件产品。它的核心价值在于：

让非技术人员用自然语言直接查询数据库，打破数据获取的瓶颈
基于 XiYan-SQL 多生成器集成框架，在 BIRD 等权威基准上保持 SOTA
支持 远程/本地双模式，兼顾速度与数据安全
零代码集成 Claude Desktop / Cursor / Goose / Cline 等主流 AI 工具

适合场景：企业内部数据分析小工具、BI 系统自然语言增强、数据库管理员辅助工具、数据合规要求高的本地部署场景。

本报告基于 GitHub 公开信息及官方文档生成，分析时间：2026-07-10