习焉 MCP 服务器

一款支持通过自然语言查询数据库的模型上下文协议(MCP)服务器
_{基于 XiYan-SQL（开源基准测试的最佳文本转SQL工具）}

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

English | 中文
钉钉集团群| 关注我的新浪微博

目录

• 功能
• 预览
  • 架构
  • 最佳实践
  • 工具预览
• 安装
  • 通过 pip 安装
  • [通过 Smithery.ai 安装](#通过sm Smithery.ai 安装)
• 配置
  • LLM 配置
    • 通用 LLMs
    • 文-本 SQL SOTA 模型
    • 本地模型
  • 数据库配置
    • MySQL
    • PostgreSQL
• 启动
  • [Claude Desktop](#克劳德桌 面)
  • Cline
  • Goose
  • Cursor
• 问题排查
• 引用

功能

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

预览

架构

有两条途径可以将此服务器集成到您的项目中，如下图所示：
左侧是远程模式（这是默认模式），它要求提供一个 API 密钥以通过服务提供商访问 xiyanSQL-qwencoder-32B 模型（详见[配置](#配置））。
另一种模式是本地模式，更安全。不需要API钥匙。

!【architecture.png](imgs/architecture.png)

最佳实践和报告

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

"孙肖MCP在Modelscope模型库上线" (https

MCPBench 上的表现评估
下图展示了 XiYan MCP 服务器在 MCPBench 基准下的表现。与 MySQL MCP 服务器和 P os tG res sQL MCP 服务器相比，XiYan MCP 服务器表现出色，领先 2-22 个百分点。详细的实验结果可查看[MCPBench](https:// )和报告[" MCP 服务器评估报告"] [ ArXiv](https://)4)。

!【exp_mcpbench.png](imgs/exp_mcpbench.png)

工具预览

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

• 当指定具体表名时，资源``{dialect}://{table_name}`允许从数据库中获得某些样本数据，用于模型参考。

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

安装

pip方式

需要 Python 3.11+ 版。
您可以从 pip 安装服务器，它将安装最新版本：

pip install xiyan-mcp-server

之后您可以直接跑服务器这样运行：

bash
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 : "XGenerati onLab/Xi YanSQL-QwenCoder -32 B-241 2"
   _key:""
 _url: "https://api - inference.models cop c n/vi_ "

 database:
  _host : "localho_s t"
   _port_: 3306
  user : "root"

    password : ""
   _database_: ''

LLM 参数设置

“Name”是需要使用的模型的名字，“Key”是该模型的 API 密匙,“URL“ 是该模型的 API 地址。
我们支持的模型列在下面表格：

| 关键 | 提供者的api密钥 | 模型service 的 api 密码 | 提供者通过电邮发放的密钥 | 留空 |

| 地址 |提供者的api地址 | https : // apj- inference .models copcn/v 1/ |https: // xiyans tr ea biz.aliyun.com/serv ice/api/xiyan -sql |http://local host:509 3 |

General LLLMs

如果您想使用g pt -3.5之类的普遍的 L LM,你可以直接按如下样例配置 :

   model :
     name : 'gpt - 3.5 tur box'
    key:' YOUR K EY' 

      url:  "https://api.op enai.c om/ Vl"
    _database:_  _ 

如果您想使用al ib b a云平台中的 q w en一 max,您可以尝试如下配置 :

    mod el :
      na me :‘qwemx’
       key:'YOUR K EE'

            url：“https: // davscope.aliyunsc om/compatible-mode/v1"
database 

文– SQL 模型最优

我们推荐XiYanSql–qwencoder——32B，即开源benchmark 中的Text to sql 最优模。型见【Bird benchmark】。

有两种办法可以使用此类模型。
1.modelscope方法
2.DashScope 方法

（1）modelscope 方法

请申请从model scope 上得到API keys 的访问权，参阅https://www.modelscope.cn/docs/modelservice/API - InferencE/i ntroduction。

然后就可以按照这种方式配置:

m od e l :
      na me: "XIYA Generation Lab/XiYA sql—qwencoder——32 b —— 2412"
   _key：“”
    u rl：“ https://api — inf eren ce.modelscope.cn/v 1/"

阅读我们的【 模型说明书】 （https: ///www.models cope.cn/models/XGeneration Lab/XiyansQL—Qwer Encoder32 b—24l2） 获取更多信息。

（1）DashScope方法

我们已经在这阿里云DashScope上部署了这个模行型，您需要进行如下的环境设置：

发送您的邮箱地址到我们以获取秘钥(g odot.Izl @alibaba-in c. com)

邮件包含以下信息即可:

name：' YOUR N AME '
ema i l: 'YOU EMAIL '
organization;'Your COllege  or com PanY Or orgA ni za tional  

根据您所填写邮箱我们将发出一封密钥邮件。然后您可以填充这个yaml中的key字段值。

秘钥将在有效期内有效或200次查询或任何其法律限定失效，详情请关注。

m aod e l: 

n a me: ' xi yans qL—qwenco der— 32 b '
k ey: '' k e y'
ul: "https://xia yans trenbiz. a li cloud.com/service/ api/ Xi yan -sql'

备注此服务为测试版，若需在产线使用请联系我们。或者您也可以选择独立部署该模型。

本地化模行

注意: 使用的模行为本地化模式速度慢。(在我的MacBook 上每十次大约会花费12 秒)如果您需要稳定高速的服务,我们仍然建议使用modelscope 版本。

要启动本地化模式您需要准备的是：

1. PC/Laptop最少需要配备16 GB存储器。

2)6-GB磁盘存储空间。

第步1: 安装其他Python包

  pip instally flask modelscopetorch==2.2.2 accelerat≥0 260 umpy—2.2. 

步骤2:（任选）手动下载模行

我们推荐xiyasnql -qwerencder 25 -3 b。（https:[ //www.modelscope.cn/sy/nods/XgenerationLa/XiYansQL-QwEncoder32b——2502）

可以手动下载模性如下 :

  modelscop d ow n load--m o d el Xgneratlonlab/xiyanSQl-q w ecnoder 3b——2502

  

将耗用您6-GB存储空间。

步骤3: 下载脚本并运行server。src/xiyan_mcp_server/local_xiyan_servr.py

 pyto rn locla_xi yan server.py  

您的server将在 http://localhost:5090

步骤4: 准备配置并运行xiyan_mcp_server.
你的config.yml文件应该被类似以下的方式写为：

model:
  name: "xiyansql-qwencoder-3b"
  key: "KET"
  url: "http://127. 0. 0 .1 : 5 09 0 "

现在您的本地化模式已就绪

数据库参数配置

“host”，” port”，“user”，” password”，“database”为数据库连接信息。

您可以使用本地安装的数据库或连接到远程数据库。目前，我们支持 M y SQL 和 Pos Tgresql。

mysqL

database:
  host: "localhost"
  port: 3306
  user: "root"
  passwod: ""
  dat abase: ''

PostgreSQL:

步骤1: 安装Python库。

pip install psycopg2

步骤2: 像此例子一样建立您的config.ylm文件 :

dat abases:
   dialect:" postgresql"

    ho t: " localhost"
    port ; 5 4 3 2 

    usa; " '

    pasword;" '
  dababases;'
'

记注意，为Postgresql 设置“dialect”应为“postgresql”。

启动

Cla udeDesktop

添加以下信息到您Claude桌面配置文件中，参照 Claude桌面配置样例</>.

{
   mcpServes:
    " X iyan- mcp_ servr':
    " commands":

    [

       '—m ',
        “ XI YA_MCS_SERVER ”

       ],
     ENV {"PATH/T/O YAML"}
}

C line

为 [Clause Desktop ] (#clause-desktop) 似配置准备 .

Goose

添加命令如下 , 参照
Goose Gooseconfig样例

env yml=path/ to/ yml python -mn yiyan_ mcp_server

Cursor

如[Goose ](#goos e)一样。

Wit sy

添加以下内容在你的指令:

python -mx iyan_mcp_ser ver 

添加一个参数，名称是"yml", 值是你自己配置文件路径
参见<Witsy 示例配置><>github.com/XGenerationLab/xian_mcp_server/blob/main/images/witysy>.png

出现问题？

联系:
<钉钉社区二维码><
<新浪微博联系我>>

引用

如果觉得对我们工作有用的话，请随意引荐。
@arxiv paper 有用文章
@article{x iys ql
标题 {APrevi ei x YanSQ l: A Mu1ti Ge n era tor Ene mb le Fr am e WorkFo r Tex to-sql }
权威 {YingtqiG aoyufi i u Xia Xiaoli Xia ro ng shi in Zhu ying Wang ShiQiL i Wei L i Yuntao Hong Z hillingL uoJ iany angGa ol iuy iou Mou YuL }
年份{2 0 2 4},
书 {arx iv Preprint arx iv:.}2415
URL: {https:/ arx iv..org abs/24}