README_zh 2.md

XiYan MCP 服务器

一种模型上下文协议（MCP）服务器，支持通过自然语言查询数据库
_{由XiYan-SQL提供技术支持，该项目在开放基准上实现了文本到SQL的最好性能}

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

英文 | 中文 | 日本語
钉钉群 | 关注我

目录

• 特性
• 预览
  • 架构
  • 最佳实践
  • 工具预览
• 安装
  • 从 pip 安装
  • 从 Smithery.ai 安装
• 配置
  • LLM 配置
    • 通用 LLMs
    • Text-to-SQL 最新模型
    • 本地模型
  • 数据库配置
    • MySQL
    • PostgreSQL
• 启动
  • Claude Desktop
  • Cline
  • Goose
  • Cursor
• 它不起作用
• 引用

特性

• 🌐 通过 XiYanSQL 使用自然语言获取数据
• 🤖 支持通用 LLMs（如 GPT, qwenmax），文本到 SQL 最新模型
• 💻 支持纯本地模式（高安全性！）
• 📝 支持 MySQL 和 PostgreSQL。
• 🖱️ 列出可用表作为资源
• 🔧 读取表内容

预览

架构

有两种方式可以将该服务器集成到您的项目中，如下图所示： 左侧是远程模式，这是默认模式。它需要 API 密钥来访问服务提供商的 xiyanSQL-qwencoder-32B 模型（请参阅配置）。 另一种模式是本地模式，更加安全，不需要 API 密钥。

最佳实践和报告

"使用 MCP + Modelscope API 推理构建本地数据助手，无需编写一行代码"

"Modelscope 上的 Xiyan MCP"

在 MCPBench 上的评估

下图展示了 XiYan MCP 服务在 MCPBench 基准测试中的表现。XiYan MCP 服务器的性能优于 MySQL MCP 服务和 PostgreSQL MCP 服务，领先 2-22 个百分点。详细的实验结果可以在 MCPBench 和报告 "MCP 服务器评估报告" 中找到。

工具预览

• 工具 get_data 提供了一个自然语言接口，用于从数据库中检索数据。该服务器将输入的自然语言转换为 SQL，并调用数据库返回查询结果。

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

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

安装

从 pip 安装

要求 Python 3.11 或更高版本。 您可以通过 pip 安装服务器，它将安装最新版本：

pip install xiyan-mcp-server

安装后，您可以直接通过以下命令运行服务器：

python -m xiyan_mcp_server

但在您完成以下配置之前，它不会提供任何功能。 您将获得一个 yml 文件。然后您可以通过以下方式运行服务器：

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

从 Smithery.ai 安装

请参见 @XGenerationLab/xiyan_mcp_server

未进行全面测试。

配置

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

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

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

LLM 配置

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

版本	通用 LLMs (GPT, qwenmax)	Modelscope 最新模型	Dashscope 最新模型	本地 LLMs
描述	基础，易于使用	性能最好，稳定，推荐	性能最好，供试用	速度慢，高安全性
名称	官方模型名称（例如 gpt-3.5-turbo, qwen-max）	XGenerationLab/XiYanSQL-QwenCoder-32B-2412	xiyansql-qwencoder-32b	xiyansql-qwencoder-3b
密钥	服务提供商的 API 密钥（例如 OpenAI, 阿里云）	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

通用 LLMs

如果您想使用通用 LLMs，如 gpt3.5，您可以直接像这样配置：

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

如果您想使用来自阿里巴巴的 Qwen，比如 Qwen-max，您可以使用以下配置：

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

Text-to-SQL 最新模型

我们推荐 XiYanSQL-qwencoder-32B（https://github.com/XGenerationLab/XiYanSQL-QwenCoder），这是文本到 SQL 的最新模型，参见 Bird benchmark。 您可以有两种方式使用该模型： (1) Modelscope， (2) 阿里云 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 版本

我们在阿里云 DashScope 上部署了模型，因此您需要设置以下环境变量： 请将您的电子邮件发送给我以获取 key。 (godot.lzl@alibaba-inc.com) 在电子邮件中，请附上以下信息：

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"
database:

注意：该模型服务仅供试用，如果您需要在生产中使用，请与我们联系。

或者，您也可以在自己的服务器上自行部署模型 XiYanSQL-qwencoder-32B。

本地模型

注意：本地模型速度较慢（在我的 MacBook 上每个查询约 12 秒）。 如果您需要稳定快速的服务，我们仍然推荐使用 Modelscope 版本。

要在本地模式下运行 xiyan_mcp_server，您需要： 1）一台至少具有 16GB 内存的 PC/Mac 2）6GB 硬盘空间

步骤 1：安装额外的 Python 包

pip install flask modelscope torch==2.2.2 accelerate>=0.26.0 numpy=2.2.3

步骤 2：（可选）手动下载模型 我们推荐 xiyansql-qwencoder-3b。 您可以手动下载模型：

modelscope download --model XGenerationLab/XiYanSQL-QwenCoder-3B-2502

这将占用您 6GB 的磁盘空间。

步骤 3：下载脚本并运行服务器。文件 src/xiyan_mcp_server/local_xiyan_server.py

python local_xiyan_server.py

服务器将在 http://localhost:5090/ 上运行。

步骤 4：准备配置并运行 xiyan_mcp_server config.yml 应如下所示：

model:
  name: "xiyansql-qwencoder-3b"
  key: "KEY"
  url: "http://127.0.0.1:5090"

到目前为止，本地模式准备就绪。

数据库配置

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: ""

注意 dialect 应为 postgresql 以适用于 PostgreSQL。

启动

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应用也是如此。

Cline

准备配置，参考 Claude Desktop

Goose

在配置中添加以下命令，参考 Goose 配置示例

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

Cursor

使用与 Goose 相同的命令。

Witsy

在命令中添加以下内容：

/xxx/python -m xiyan_mcp_server

添加一个环境变量：键为 YML，值为您 yml 文件的路径。 参考 Witsy 配置示例

它不起作用！

请联系我们： 钉钉群｜ 关注我

引用

如果您觉得我们的工作有帮助，可以随意引用。

@article{xiyansql,
      title={A Preview of XiYan-SQL: A Multi-Generator Ensemble Framework for Text-to-SQL}, 
      author={Yingqi Gao and Yifu Liu and Xiaoxia Li and Xiaorong Shi and Yin Zhu and Yiming Wang and Shiqi Li and Wei Li and Yuntao Hong and Zhiling Luo and Jinyang Gao and Liyu Mou and Yu Li},
      year={2024},
      journal={arXiv preprint arXiv:2411.08599},
      url={https://arxiv.org/abs/2411.08599},
      primaryClass={cs.AI}
}