XiYan MCP Server

<h1 align="center">析言 MCP 服务器</h1> <p align="center"> <a href="https://github.com/XGenerationLab/XiYan-SQL"><img alt="MCP Playwright" src="https://raw.githubusercontent.com/XGenerationLab/XiYan-SQL/main/xiyanGBI.png" height="60"/></a> </p> <p align="center"> <b>一个模型上下文协议 (MCP) 服务器，支持使用自然语言查询数据库</b><br/> _{由 <a href="https://github.com/XGenerationLab/XiYan-SQL" >XiYan-SQL</a> 驱动，在开放基准测试中达到 Text-to-SQL 的 SOTA} </p>

<p align="center"> 💻 <a href="https://github.com/XGenerationLab/xiyan_mcp_server" >XiYan-mcp-server</a> | 🌐 <a href="https://github.com/XGenerationLab/XiYan-SQL" >XiYan-SQL</a> | 📖 <a href="https://arxiv.org/abs/2411.08599"> Arxiv</a> | 📄 <a href="https://paperswithcode.com/paper/xiyan-sql-a-multi-generator-ensemble" >PapersWithCode</a> 💻 <a href="https://huggingface.co/collections/XGenerationLab/xiyansql-models-67c9844307b49f87436808fc">HuggingFace</a> | 🤖 <a href="https://modelscope.cn/collections/XiYanSQL-Models-4483337b614241" >ModelScope</a> | 🌕 <a href="https://bailian.console.aliyun.com/xiyan">析言GBI</a> <br /> <a href="https://arxiv.org/abs/2411.08599"><img src="imgs/Paper-Arxiv-orange.svg" ></a> <a href="https://opensource.org/licenses/Apache-2.0"> <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0" /> </a> <a href="https://pepy.tech/projects/xiyan-mcp-server"><img src="https://static.pepy.tech/badge/xiyan-mcp-server" alt="PyPI Downloads"></a> <a href="https://smithery.ai/server/@XGenerationLab/xiyan_mcp_server"><img alt="Smithery Installs" src="https://smithery.ai/badge/@XGenerationLab/xiyan_mcp_server" height="20"/></a> <a href="https://github.com/XGenerationLab/xiyan_mcp_server" target="_blank"> <img src="https://img.shields.io/github/stars/XGenerationLab/xiyan_mcp_server?style=social" alt="GitHub stars" /> </a> <br /> <a href="https://github.com/XGenerationLab/xiyan_mcp_server" >English</a> | <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/README_zh.md"> 中文 </a><br /> <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/imgs/dinggroup_out.png">Ding Group钉钉群</a>｜ <a href="https://weibo.com/u/2540915670" target="_blank">Follow me on Weibo</a> </p>

目录

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

特性

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

预览

架构

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

最佳实践

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

工具预览

• 工具 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 url。 我们支持以下模型。

版本	通用 LLM（GPT、qwenmax）	Modelscope 的 SOTA 模型	Dashscope 的 SOTA 模型	本地 LLM
描述	基本，易于使用	最佳性能，稳定，推荐	最佳性能，用于试用	慢，高安全性
名称	官方模型名称（例如 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

通用 LLM

如果您想使用通用 LLM，例如 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 SOTA 模型

我们推荐 XiYanSQL-qwencoder-32B (https://github.com/XGenerationLab/XiYanSQL-QwenCoder)，它是 text-to-sql 中的 SOTA 模型，请参阅 Bird 基准。 有两种方法可以使用该模型。 您可以使用其中任何一种。 (1) Modelscope, (2) 阿里云 DashScope。

(1) Modelscope 版本

您需要从 Modelscope 申请 API-inference 的 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: "您的姓名",
email: "您的电子邮件",
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 RAM 的 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: ""

请注意，对于 postgresql，dialect 应该是 postgresql。

启动

Claude Desktop

将此添加到您的 Claude Desktop 配置文件中，参考 <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/imgs/claude_desktop.jpg">Claude Desktop 配置示例</a>

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

Cline

准备配置，如 Claude Desktop

Goose

在配置中添加以下命令，参考 <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/imgs/goose.jpg">Goose 配置示例</a>

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

Cursor

使用与 Goose 相同的命令。

Witsy

在命令中添加以下内容：

python -m xiyan_mcp_server

添加一个 env：key 是 YML，value 是您的 yml 文件的路径。 参考 <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/imgs/witsy.jpg">Witsy 配置示例</a>

无法工作！

联系我们： <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/imgs/dinggroup_out.png">Ding Group钉钉群</a>｜ <a href="https://weibo.com/u/2540915670" target="_blank">Follow me on Weibo</a>

引用

如果您发现我们的工作有帮助，请随时引用我们。

@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}
}