Skip to content
Back to search

xiyan_mcp_server

A Model Context Protocol (MCP) server that enables natural language queries to databases

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/xgenerationlab--xiyan-mcp-server/badge.svg)](/listings/xgenerationlab--xiyan-mcp-server)

HTML

<a href="/listings/xgenerationlab--xiyan-mcp-server"><img src="/api/listings/xgenerationlab--xiyan-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Installing from pip

Python 3.11+ is required. You can install the server through pip, and it will install the latest version:

pip install xiyan-mcp-server

If you want to install the development version from source, you can install from source code on github:

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

Installing from Smithery.ai

See [@XGenerationLab/xiyan_mcp_server](https://smithery.ai/server/@XGenerationLab/xiyan_mcp_server)

Not fully tested.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 383 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <h1 align="center">XiYan MCP Server</h1>
  2. <p align="center">
  3. <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>
  4. </p>
  5. <p align="center">
  6. <b>A Model Context Protocol (MCP) server that enables natural language queries to databases</b><br/>
  7. <sub>powered by <a href="https://github.com/XGenerationLab/XiYan-SQL" >XiYan-SQL</a>, SOTA of text-to-sql on open benchmarks</sub>
  8. </p>
  9. <p align="center">
  10. 💻 <a href="https://github.com/XGenerationLab/xiyan_mcp_server" >XiYan-mcp-server</a> |
  11. 🌐 <a href="https://github.com/XGenerationLab/XiYan-SQL" >XiYan-SQL</a> |
  12. 📖 <a href="https://arxiv.org/abs/2507.04701"> Arxiv</a> |
  13. 🏆 <a href="https://github.com/XGenerationLab/XiYanSQL-QwenCoder" >XiYanSQL Model</a> |
  14. 📄 <a href="https://paperswithcode.com/paper/xiyan-sql-a-multi-generator-ensemble" >PapersWithCode</a>
  15. 🤗 <a href="https://huggingface.co/collections/XGenerationLab/xiyansql-models-67c9844307b49f87436808fc">HuggingFace</a> |
  16. 🤖 <a href="https://modelscope.cn/collections/XiYanSQL-Models-4483337b614241" >ModelScope</a> |
  17. 🌕 <a href="https://bailian.console.aliyun.com/xiyan">析言GBI</a>
  18. <br />
  19. <img src="https://badge.mcpx.dev/?type=server%20%27MCP%20Server%27" alt="MCP Server" />
  20. <a href="https://arxiv.org/abs/2411.08599"><img src="imgs/Paper-Arxiv-orange.svg" ></a>
  21. <a href="https://opensource.org/licenses/Apache-2.0">
  22. <img src="https://img.shields.io/badge/License-Apache%202.0-blue.svg" alt="License: Apache 2.0" />
  23. </a>
  24. <a href="https://pepy.tech/projects/xiyan-mcp-server"><img src="https://static.pepy.tech/badge/xiyan-mcp-server" alt="PyPI Downloads"></a>
  25. [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/XGenerationLab/xiyan_mcp_server)](https://archestra.ai/mcp-catalog/xgenerationlab__xiyan_mcp_server)
  26. <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>
  27. <a href="https://github.com/XGenerationLab/xiyan_mcp_server" target="_blank">
  28. <img src="https://img.shields.io/github/stars/XGenerationLab/xiyan_mcp_server?style=social" alt="GitHub stars" />
  29. </a>
  30. <br />
  31. <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> | <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/README_ja.md"> 日本語 </a><br />
  32. <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/imgs/dinggroup_out.png">Ding Group钉钉群</a>|
  33. <a href="https://weibo.com/u/2540915670" target="_blank">Follow me on Weibo</a>
  34. </p>
  35. ## Table of Contents
  36. - [Features](#features)
  37. - [Preview](#preview)
  38. - [Architecture](#architecture)
  39. - [Best Practice](#best-practice)
  40. - [Tools Preview](#tools-preview)
  41. - [Installation](#installation)
  42. - [Installing from pip](#installing-from-pip)
  43. - [Installing from Smithery.ai](#installing-from-smitheryai)
  44. - [Configuration](#configuration)
  45. - [LLM Configuration](#llm-configuration)
  46. - [General LLMs](#general-llms)
  47. - [Text-to-SQL SOTA model](#text-to-sql-sota-model)
  48. - [Local Model](#local-model)
  49. - [Database Configuration](#database-configuration)
  50. - [MySQL](#mysql)
  51. - [PostgreSQL](#postgresql)
  52. - [Launch](#launch)
  53. - [Claude Desktop](#claude-desktop)
  54. - [Cline](#cline)
  55. - [Goose](#goose)
  56. - [Cursor](#cursor)
  57. - [It Does Not Work](#it-does-not-work)
  58. - [Citation](#citation)
  59. ## Features
  60. - 🌐 Fetch data by natural language through [XiYanSQL](https://github.com/XGenerationLab/XiYan-SQL)
  61. - 🤖 Support general LLMs (GPT,qwenmax), Text-to-SQL SOTA model
  62. - 💻 Support pure local mode (high security!)
  63. - 📝 Support MySQL and PostgreSQL.
  64. - 🖱️ List available tables as resources
  65. - 🔧 Read table contents
  66. ## Preview
  67. ### Architecture
  68. There are two ways to integrate this server in your project, as shown below:
  69. The left is remote mode, which is the default mode. It requires an API key to access the xiyanSQL-qwencoder-32B model from service provider (see [Configuration](#Configuration)).
  70. Another mode is local mode, which is more secure. It does not require the API key.
  71. ![architecture.png](imgs/architecture.png)
  72. ### Best practice and reports
  73. ["Build a local data assistant using MCP + Modelscope API-Inference without writing a single line of code"](https://mp.weixin.qq.com/s/tzDelu0W4w6t9C0_yYRbHA)
  74. ["Xiyan MCP on Modelscope"](https://modelscope.cn/headlines/article/1142)
  75. ### Evaluation on MCPBench
  76. The following figure illustrates the performance of the XiYan MCP server as measured by the MCPBench benchmark. The XiYan MCP server demonstrates superior performance compared to both the MySQL MCP server and the PostgreSQL MCP server, achieving a lead of 2-22 percentage points. The detailed experiment results can be found at [MCPBench](https://github.com/modelscope/MCPBench) and the report ["Evaluation Report on MCP Servers"](https://arxiv.org/abs/2504.11094).
  77. ![exp_mcpbench.png](imgs/exp_mcpbench.png)
  78. ### Tools Preview
  79. - The tool ``get_data`` provides a natural language interface for retrieving data from a database. This server will convert the input natural language into SQL using a built-in model and call the database to return the query results.
  80. - The ``{dialect}://{table_name}`` resource allows obtaining a portion of sample data from the database for model reference when a specific table_name is specified.
  81. - The ``{dialect}://`` resource will list the names of the current databases
  82. ## Installation
  83. ### Installing from pip
  84. Python 3.11+ is required.
  85. You can install the server through pip, and it will install the latest version:
  86. ```shell
  87. pip install xiyan-mcp-server
  88. ```
  89. If you want to install the development version from source, you can install from source code on github:
  90. ```shell
  91. pip install git+https://github.com/XGenerationLab/xiyan_mcp_server.git
  92. ```
  93. ### Installing from Smithery.ai
  94. See [@XGenerationLab/xiyan_mcp_server](https://smithery.ai/server/@XGenerationLab/xiyan_mcp_server)
  95. Not fully tested.
  96. ## Configuration
  97. You need a YAML config file to configure the server.
  98. A default config file is provided in config_demo.yml which looks like this:
  99. ```yaml
  100. mcp:
  101. transport: "stdio"
  102. model:
  103. name: "XGenerationLab/XiYanSQL-QwenCoder-32B-2412"
  104. key: ""
  105. url: "https://api-inference.modelscope.cn/v1/"
  106. database:
  107. host: "localhost"
  108. port: 3306
  109. user: "root"
  110. password: ""
  111. database: ""
  112. ```
  113. ### MCP Configuration
  114. You can set the transport protocol to ``stdio`` or ``sse``.
  115. #### STDIO
  116. For stdio protocol, you can set just like this:
  117. ```yaml
  118. mcp:
  119. transport: "stdio"
  120. ```
  121. #### SSE
  122. For sse protocol, you can set mcp config as below:
  123. ```yaml
  124. mcp:
  125. transport: "sse"
  126. port: 8000
  127. log_level: "INFO"
  128. ```
  129. The default port is `8000`. You can change the port if needed.
  130. The default log level is `ERROR`. We recommend to set log level to `INFO` for more detailed information.
  131. Other configurations like `debug`, `host`, `sse_path`, `message_path` can be customized as well, but normally you don't need to modify them.
  132. ### LLM Configuration
  133. ``Name`` is the name of the model to use, ``key`` is the API key of the model, ``url`` is the API url of the model. We support following models.
  134. | versions | general LLMs(GPT,qwenmax) | SOTA model by Modelscope | SOTA model by Dashscope | Local LLMs |
  135. |----------|-------------------------------|--------------------------------------------|-----------------------------------------------------------|-----------------------|
  136. | description| basic, easy to use | best performance, stable, recommand | best performance, for trial | slow, high-security |
  137. | name | the official model name (e.g. gpt-3.5-turbo,qwen-max) | XGenerationLab/XiYanSQL-QwenCoder-32B-2412 | xiyansql-qwencoder-32b | xiyansql-qwencoder-3b |
  138. | key | the API key of the service provider (e.g. OpenAI, Alibaba Cloud) | the API key of modelscope | the API key via email | "" |
  139. | url | the endpoint of the service provider (e.g."https://api.openai.com/v1") | https://api-inference.modelscope.cn/v1/ | https://xiyan-stream.biz.aliyun.com/service/api/xiyan-sql | http://localhost:5090 |
  140. #### General LLMs
  141. If you want to use the general LLMs, e.g. gpt3.5, you can directly config like this:
  142. ```yaml
  143. model:
  144. name: "gpt-3.5-turbo"
  145. key: "YOUR KEY "
  146. url: "https://api.openai.com/v1"
  147. database:
  148. ```
  149. If you want to use Qwen from Alibaba, e.g. Qwen-max, you can use following config:
  150. ```yaml
  151. model:
  152. name: "qwen-max"
  153. key: "YOUR KEY "
  154. url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  155. database:
  156. ```
  157. #### Text-to-SQL SOTA model
  158. We recommend the XiYanSQL-qwencoder-32B (https://github.com/XGenerationLab/XiYanSQL-QwenCoder), which is the SOTA model in text-to-sql, see [Bird benchmark](https://bird-bench.github.io/).
  159. There are two ways to use the model. You can use either of them.
  160. (1) [Modelscope](https://www.modelscope.cn/models/XGenerationLab/XiYanSQL-QwenCoder-32B-2412), (2) Alibaba Cloud DashScope.
  161. ##### (1) Modelscope version
  162. You need to apply a ``key`` of API-inference from Modelscope, https://www.modelscope.cn/docs/model-service/API-Inference/intro
  163. Then you can use the following config:
  164. ```yaml
  165. model:
  166. name: "XGenerationLab/XiYanSQL-QwenCoder-32B-2412"
  167. key: ""
  168. url: "https://api-inference.modelscope.cn/v1/"
  169. ```
  170. Read our [model description](https://www.modelscope.cn/models/XGenerationLab/XiYanSQL-QwenCoder-32B-2412) for more details.
  171. ##### (2) Dashscope version
  172. We deployed the model on Alibaba Cloud DashScope, so you need to set the following environment variables:
  173. Send me your email to get the ``key``. ( godot.lzl@alibaba-inc.com )
  174. In the email, please attach the following information:
  175. ```yaml
  176. name: "YOUR NAME",
  177. email: "YOUR EMAIL",
  178. organization: "your college or Company or Organization"
  179. ```
  180. We will send you a ``key`` according to your email. And you can fill the ``key`` in the yml file.
  181. The ``key`` will be expired by 1 month or 200 queries or other legal restrictions.
  182. ```yaml
  183. model:
  184. name: "xiyansql-qwencoder-32b"
  185. key: "KEY"
  186. url: "https://xiyan-stream.biz.aliyun.com/service/api/xiyan-sql"
  187. ```
  188. Note: this model service is just for trial, if you need to use it in production, please contact us.
  189. ##### (3) Local version
  190. Alternatively, you can also deploy the model [XiYanSQL-qwencoder-32B](https://github.com/XGenerationLab/XiYanSQL-QwenCoder) on your own server.
  191. See [Local Model](src/xiyan_mcp_server/local_model/README.md) for more details.
  192. ### Database Configuration
  193. ``host``, ``port``, ``user``, ``password``, ``database`` are the connection information of the database.
  194. You can use local or any remote databases. Now we support MySQL and PostgreSQL(more dialects soon).
  195. #### MySQL
  196. ```yaml
  197. database:
  198. host: "localhost"
  199. port: 3306
  200. user: "root"
  201. password: ""
  202. database: ""
  203. ```
  204. #### PostgreSQL
  205. Step 1: Install Python packages
  206. ```bash
  207. pip install psycopg2
  208. ```
  209. Step 2: prepare the config.yml like this:
  210. ```yaml
  211. database:
  212. dialect: "postgresql"
  213. host: "localhost"
  214. port: 5432
  215. user: ""
  216. password: ""
  217. database: ""
  218. ```
  219. Note that ``dialect`` should be ``postgresql`` for postgresql.
  220. ## Launch
  221. ### Server Launch
  222. If you want to launch server with `sse`, you have to run the following command in a terminal:
  223. ```shell
  224. YML=path/to/yml python -m xiyan_mcp_server
  225. ```
  226. Then you should see the information on http://localhost:8000/sse in your browser. (Defaultly, change if your mcp server runs on other host/port)
  227. Otherwise, if you use `stdio` transport protocol, you usually declare the mcp server command in specific mcp application instead of launching it in a terminal.
  228. However, you can still debug with this command if needed.
  229. ### Client Setting
  230. #### Claude Desktop
  231. Add this in your Claude Desktop config file, ref <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/imgs/claude_desktop.jpg">Claude Desktop config example</a>
  232. ```json
  233. {
  234. "mcpServers": {
  235. "xiyan-mcp-server": {
  236. "command": "/xxx/python",
  237. "args": [
  238. "-m",
  239. "xiyan_mcp_server"
  240. ],
  241. "env": {
  242. "YML": "PATH/TO/YML"
  243. }
  244. }
  245. }
  246. }
  247. ```
  248. **Please note that the Python command here requires the complete path to the Python executable (`/xxx/python`); otherwise, the Python interpreter cannot be found. You can determine this path by using the command `which python`. The same applies to other applications as well.**
  249. Claude Desktop currently does not support the SSE transport protocol.
  250. #### Cline
  251. Prepare the config like [Claude Desktop](#claude-desktop)
  252. #### Goose
  253. If you use `stdio`, add following command in the config, ref <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/imgs/goose.jpg">Goose config example</a>
  254. ```shell
  255. env YML=path/to/yml /xxx/python -m xiyan_mcp_server
  256. ```
  257. Otherwise, if you use `sse`, change Type to `SSE` and set the endpoint to `http://127.0.0.1:8000/sse`
  258. #### Cursor
  259. Use the similar command as follows.
  260. For `stdio`:
  261. ```json
  262. {
  263. "mcpServers": {
  264. "xiyan-mcp-server": {
  265. "command": "/xxx/python",
  266. "args": [
  267. "-m",
  268. "xiyan_mcp_server"
  269. ],
  270. "env": {
  271. "YML": "path/to/yml"
  272. }
  273. }
  274. }
  275. }
  276. ```
  277. For `sse`:
  278. ```json
  279. {
  280. "mcpServers": {
  281. "xiyan_mcp_server_1": {
  282. "url": "http://localhost:8000/sse"
  283. }
  284. }
  285. }
  286. ```
  287. #### Witsy
  288. Add following in command:
  289. ```shell
  290. /xxx/python -m xiyan_mcp_server
  291. ```
  292. Add an env: key is YML and value is the path to your yml file.
  293. Ref <a href="https://github.com/XGenerationLab/xiyan_mcp_server/blob/main/imgs/witsy.jpg">Witsy config example</a>
  294. ## Contact us:
  295. If you are interested in our research or products, please feel free to contact us.
  296. #### Contact Information:
  297. Yifu Liu, zhencang.lyf@alibaba-inc.com
  298. #### Join Our DingTalk Group
  299. <a href="https://github.com/XGenerationLab/XiYan-SQL/blob/main/xiyansql_dingding.png">Ding Group钉钉群</a>
  300. ## Other Related Links
  301. [![MseeP.ai Security Assessment Badge](https://mseep.net/pr/xgenerationlab-xiyan-mcp-server-badge.png)](https://mseep.ai/app/xgenerationlab-xiyan-mcp-server)
  302. ## Citation
  303. If you find our work helpful, feel free to give us a cite.
  304. ```bibtex
  305. @article{XiYanSQL,
  306. title={XiYan-SQL: A Novel Multi-Generator Framework For Text-to-SQL},
  307. 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},
  308. year={2025},
  309. eprint={2507.04701},
  310. archivePrefix={arXiv},
  311. primaryClass={cs.CL},
  312. url={https://arxiv.org/abs/2507.04701},
  313. }
  314. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.