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 上取得好成绩，意味着在实际企业数据库场景中同样可靠。

图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 的工作流程如下：

1. 接收自然语言查询："北京区域 Q1 销售额超过 100 万的客户有哪些？"
2. 获取数据库 Schema：通过 MCP Resource 接口读取目标数据库的表结构（列名、数据类型、外键关系）
3. 调用 XiYan-SQL 模型：将自然语言 + Schema 组合成 Prompt，送给 Text-to-SQL 模型
4. 生成并执行 SQL：生成的 SQL 经过安全校验后，在数据库中执行
5. 返回结构化结果：以 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 之间的网络连接。

图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 的产品"，即可得到结果。

图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