XiYan MCP Server

XiYan MCP Server

一款支持使用自然语言查询数据库的模型上下文协议（MCP）服务
_{由 XiYan-SQL 提供支持，在公开基准测试的文本转 SQL 任务中达到 SOTA}

💻 XiYan-mcp-server | 🌐 XiYan-SQL | 📖 Arxiv | 🏆 XiYanSQL Model | 📄 PapersWithCode 🤗 HuggingFace | 🤖 ModelScope | 🌕 析言GBI

English | 中文 | 日本語
Ding Group 钉钉群｜ 在微博关注我

目录

• 功能
• 预览
  • 架构
  • 最佳实践
  • 工具预览
• 安装
  • 通过 pip 安装
  • 通过 Smithery.ai 安装
• 配置
  • 大模型配置
    • 通用大模型
    • 文本转 SQL SOTA 模型
    • 本地模型
  • 数据库配置
    • MySQL
    • PostgreSQL
• 启动
  • Claude Desktop
  • Cline
  • Goose
  • Cursor
• 无法正常工作
• 引用

功能

• 🌐 通过 XiYanSQL 使用自然语言获取数据
• 🤖 支持通用大模型（GPT、qwenmax）和文本转 SQL SOTA 模型
• 💻 支持纯本地模式（安全性高！）
• 📝 支持 MySQL 和 PostgreSQL。
• 🖱️ 将可用表列为资源
• 🔧 读取表内容

预览

架构

如下所示，有两种方式可将此服务集成到项目中： 左侧为远程模式，也是默认模式。此模式需要 API 密钥才能访问服务提供商提供的 xiyanSQL-qwencoder-32B 模型（参见配置）。 另一种模式是本地模式，更安全，且不需要 API 密钥。

最佳实践与报告

“无需编写任何代码，使用 MCP + Modelscope API-Inference 构建本地数据助手”

“Modelscope 上的 Xiyan MCP”

MCPBench 评测

下图展示了 XiYan MCP 服务在 MCPBench 基准测试中的表现。与 MySQL MCP 服务和 PostgreSQL MCP 服务相比，XiYan MCP 服务表现更优，领先 2–22 个百分点。详细实验结果可见 MCPBench 和报告“MCP 服务评测报告”。

工具预览

• 工具 get_data 提供了一个用于从数据库获取数据的自然语言接口。此服务会使用内置模型将输入的自然语言转换为 SQL，并调用数据库返回查询结果。

• {dialect}://{table_name} 资源允许在指定 table_name 时，从数据库获取部分样例数据，供模型参考。

• {dialect}:// 资源会列出当前数据库的名称

安装

从 pip 安装

需要 Python 3.11+。 你可以通过 pip 安装此服务，安装的将是最新版本：

pip install xiyan-mcp-server

如果你想从源代码安装开发版本，可以从 github 上的源代码安装：

pip install git+https://github.com/XGenerationLab/xiyan_mcp_server.git

从 Smithery.ai 安装

请参见 @XGenerationLab/xiyan_mcp_server

尚未经过完整测试。

配置

你需要一个 YAML 配置文件来配置此服务。 我们提供了默认配置文件 config_demo.yml，内容如下：

mcp:
  transport: "stdio"
model:
  name: "XGenerationLab/XiYanSQL-QwenCoder-32B-2412"
  key: ""
  url: "https://api-inference.modelscope.cn/v1/"
database:
  host: "localhost"
  port: 3306
  user: "root"
  password: ""
  database: ""

MCP 配置

你可以将传输协议设置为 stdio 或 sse。

STDIO

对于 stdio 协议，可以这样设置：

mcp:
  transport: "stdio"

SSE

对于 sse 协议，可以按如下方式设置 mcp 配置：

mcp:
  transport: "sse"
  port: 8000
  log_level: "INFO"

默认端口为 8000。你可以根据需要更改端口。 默认日志级别为 ERROR。我们建议将日志级别设置为 INFO，以获取更详细的信息。

还可以自定义 debug、host、sse_path、message_path 等配置，但通常无需修改。

大模型配置

Name 是要使用的模型名称，key 是模型的 API 密钥，url 是模型的 API 地址。我们支持以下模型。

versions	通用大模型（GPT、qwenmax）	Modelscope 的 SOTA 模型	Dashscope 的 SOTA 模型	本地大模型
description	基础、易用	性能最佳、稳定，推荐使用	性能最佳，可供试用	速度慢、安全性高
name	官方模型名称（例如 gpt-3.5-turbo、qwen-max）	XGenerationLab/XiYanSQL-QwenCoder-32B-2412	xiyansql-qwencoder-32b	xiyansql-qwencoder-3b
key	服务提供商的 API 密钥（例如 OpenAI、Alibaba Cloud）	Modelscope 的 API 密钥	通过电子邮件获取的 API 密钥	""
url	服务提供商的端点（例如 "https://api.openai.com/v1"）	https://api-inference.modelscope.cn/v1/	https://xiyan-stream.biz.aliyun.com/service/api/xiyan-sql	http://localhost:5090

通用大模型

如果要使用通用大模型，例如 gpt3.5，可以直接按如下方式配置：

model:
  name: "gpt-3.5-turbo"
  key: "YOUR KEY "
  url: "https://api.openai.com/v1"
database:

如果要使用 Alibaba 的 Qwen，例如 Qwen-max，可以使用以下配置：

model:
  name: "qwen-max"
  key: "YOUR KEY "
  url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
database:

文本转 SQL SOTA 模型

我们推荐 XiYanSQL-qwencoder-32B（https://github.com/XGenerationLab/XiYanSQL-QwenCoder），它是文本转 SQL 领域的 SOTA 模型，参见 Bird 基准测试。 使用该模型有两种方式，可以任选其一。 (1) Modelscope，(2) Alibaba Cloud DashScope。

(1) Modelscope 版本

你需要申请 Modelscope 的 API 推理 key，请访问 https://www.modelscope.cn/docs/model-service/API-Inference/intro 然后可以使用以下配置：

model:
  name: "XGenerationLab/XiYanSQL-QwenCoder-32B-2412"
  key: ""
  url: "https://api-inference.modelscope.cn/v1/"

更多详情请阅读我们的模型说明。

(2) Dashscope 版本

我们已在 Alibaba Cloud DashScope 上部署该模型，因此你需要设置以下环境变量： 请将你的电子邮件发送给我以获取 key。（[email protected]） 邮件中请附上以下信息：

name: "YOUR NAME",
email: "YOUR EMAIL",
organization: "your college or Company or Organization"

我们会根据你的电子邮件向你发送 key。然后你可以在 yml 文件中填写 key。 key 将在 1 个月、200 次查询或其他法律限制到期时失效。

model:
  name: "xiyansql-qwencoder-32b"
  key: "KEY"
  url: "https://xiyan-stream.biz.aliyun.com/service/api/xiyan-sql"

注意：此模型服务仅供试用。如果你需要在生产环境中使用，请联系我们。

(3) 本地版本

你也可以将模型 XiYanSQL-qwencoder-32B 部署到自己的服务器上。 更多详情请参见本地模型。

数据库配置

host、port、user、password、database 是数据库的连接信息。

你可以使用本地数据库或任意远程数据库。目前我们支持 MySQL 和 PostgreSQL（之后将支持更多方言）。

MySQL

database:
  host: "localhost"
  port: 3306
  user: "root"
  password: ""
  database: ""

PostgreSQL

步骤 1：安装 Python 包

pip install psycopg2

步骤 2：按如下方式准备 config.yml：

database:
  dialect: "postgresql"
  host: "localhost"
  port: 5432
  user: ""
  password: ""
  database: ""

注意，PostgreSQL 的 dialect 应为 postgresql。

启动

服务启动

如果要通过 sse 启动服务，请在终端中运行以下命令：

YML=path/to/yml python -m xiyan_mcp_server

然后，你应该可以在浏览器中看到 http://localhost:8000/sse 上的信息。（默认地址；如果你的 mcp 服务运行在其他主机或端口上，请相应修改。）

如果使用 stdio 传输协议，通常需要在特定的 mcp 应用中声明 mcp 服务命令，而不是在终端中启动。 不过，如有需要，你仍然可以使用此命令进行调试。

客户端设置

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中，参见 Claude Desktop 配置示例

{
    "mcpServers": {
        "xiyan-mcp-server": {
            "command": "/xxx/python",
            "args": [
                "-m",
                "xiyan_mcp_server"
            ],
            "env": {
                "YML": "PATH/TO/YML"
            }
        }
    }
}

请注意，此处的 Python 命令需要使用 Python 可执行文件的完整路径（/xxx/python）；否则，将无法找到 Python 解释器。你可以使用命令 which python 确定此路径。其他应用也同样如此。

Claude Desktop 目前不支持 SSE 传输协议。

Cline

按照 Claude Desktop 准备配置

Goose

如果使用 stdio，请在配置中添加以下命令，参见 Goose 配置示例

env YML=path/to/yml /xxx/python -m xiyan_mcp_server

如果使用 sse，则将 Type 改为 SSE，并将 endpoint 设置为 http://127.0.0.1:8000/sse

Cursor

使用类似以下的命令。

对于 stdio：

{
  "mcpServers": {
    "xiyan-mcp-server": {
      "command": "/xxx/python",
      "args": [
        "-m",
        "xiyan_mcp_server"
      ],
      "env": {
        "YML": "path/to/yml"
      }
    }
  }
}

对于 sse：

{
  "mcpServers": {
    "xiyan_mcp_server_1": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Witsy

在 command 中添加以下内容：

/xxx/python -m xiyan_mcp_server

添加一个 env：键为 YML，值为你的 yml 文件路径。 参见 Witsy 配置示例

联系我们：

如果你对我们的研究或产品感兴趣，欢迎随时联系我们。

联系方式：

Yifu Liu，[email protected]

加入我们的钉钉群

钉钉群

其他相关链接

引用

如果我们的工作对你有所帮助，欢迎引用。

@article{XiYanSQL,
      title={XiYan-SQL: A Novel Multi-Generator Framework For Text-to-SQL}, 
      author={Yifu Liu and Yin Zhu and Yingqi Gao and Zhiling Luo and Xiaoxia Li and Xiaorong Shi and Yuntao Hong and Jinyang Gao and Yu Li and Bolin Ding and Jingren Zhou},
      year={2025},
      eprint={2507.04701},
      archivePrefix={arXiv},
      primaryClass={cs.CL},
      url={https://arxiv.org/abs/2507.04701}, 
}