XiYan MCP Server

XiYan MCP Server

Um servidor Model Context Protocol (MCP) que permite consultas em linguagem natural a bancos de dados
_{alimentado por XiYan-SQL, SOTA de text-to-sql em benchmarks abertos}

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

English | 中文 | 日本語
Ding Group钉钉群｜ Follow me on Weibo

Sumário

• Recursos
• Pré-visualização
  • Arquitetura
  • Melhores práticas
  • Pré-visualização das ferramentas
• Instalação
  • Instalação via pip
  • Instalação via Smithery.ai
• Configuração
  • Configuração do LLM
    • LLMs gerais
    • Modelo SOTA de Text-to-SQL
    • Modelo local
  • Configuração do banco de dados
    • MySQL
    • PostgreSQL
• Inicialização
  • Claude Desktop
  • Cline
  • Goose
  • Cursor
• Não funciona
• Citação

Recursos

• 🌐 Busque dados por linguagem natural através do XiYanSQL
• 🤖 Suporte a LLMs gerais (GPT, qwenmax), modelo SOTA de Text-to-SQL
• 💻 Suporte a modo totalmente local (alta segurança!)
• 📝 Suporte a MySQL e PostgreSQL.
• 🖱️ Liste tabelas disponíveis como recursos
• 🔧 Leia o conteúdo das tabelas

Pré-visualização

Arquitetura

Há duas maneiras de integrar este servidor ao seu projeto, conforme mostrado abaixo: À esquerda está o modo remoto, que é o modo padrão. Ele requer uma chave de API para acessar o modelo xiyanSQL-qwencoder-32B do provedor de serviços (veja Configuração). Outro modo é o modo local, que é mais seguro. Ele não requer a chave de API.

Melhores práticas e relatórios

"Construa um assistente de dados local usando MCP + Modelscope API-Inference sem escrever uma única linha de código"

"Xiyan MCP no Modelscope"

Avaliação no MCPBench

A figura a seguir ilustra o desempenho do servidor XiYan MCP conforme medido pelo benchmark MCPBench. O servidor XiYan MCP demonstra desempenho superior em comparação tanto ao servidor MySQL MCP quanto ao servidor PostgreSQL MCP, alcançando uma vantagem de 2 a 22 pontos percentuais. Os resultados detalhados dos experimentos podem ser encontrados em MCPBench e no relatório "Relatório de Avaliação de Servidores MCP".

Pré-visualização das ferramentas

• A ferramenta get_data fornece uma interface em linguagem natural para recuperar dados de um banco de dados. Este servidor converterá a linguagem natural de entrada em SQL usando um modelo integrado e chamará o banco de dados para retornar os resultados da consulta.

• O recurso {dialect}://{table_name} permite obter uma parte dos dados de amostra do banco de dados para referência do modelo quando um nome de tabela específico é informado.

• O recurso {dialect}:// listará os nomes dos bancos de dados atuais

Instalação

Instalação via pip

Python 3.11+ é necessário. Você pode instalar o servidor via pip, e ele instalará a versão mais recente:

pip install xiyan-mcp-server

Se você quiser instalar a versão de desenvolvimento a partir do código-fonte, pode instalá-la a partir do código-fonte no github:

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

Instalação via Smithery.ai

Veja @XGenerationLab/xiyan_mcp_server

Não totalmente testado.

Configuração

Você precisa de um arquivo de configuração YAML para configurar o servidor. Um arquivo de configuração padrão é fornecido em config_demo.yml, que se parece com isto:

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

Configuração do MCP

Você pode definir o protocolo de transporte como stdio or sse.

STDIO

Para o protocolo stdio, você pode configurar assim:

mcp:
  transport: "stdio"

SSE

Para o protocolo sse, você pode configurar o mcp da seguinte forma:

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

A porta padrão é 8000. Você pode alterar a porta se necessário. O nível de log padrão é ERROR. Recomendamos definir o nível de log como INFO para informações mais detalhadas.

Outras configurações como debug, host, sse_path, message_path também podem ser personalizadas, mas normalmente você não precisa modificá-las.

Configuração do LLM

Name is the name of the model to use, key is the API key of the model, url é a URL da API do modelo. Suportamos os seguintes modelos.

versões	LLMs gerais (GPT, qwenmax)	Modelo SOTA via Modelscope	Modelo SOTA via Dashscope	LLMs locais
descrição	básico, fácil de usar	melhor desempenho, estável, recomendado	melhor desempenho, para teste	lento, alta segurança
nome	o nome oficial do modelo (ex.: gpt-3.5-turbo, qwen-max)	XGenerationLab/XiYanSQL-QwenCoder-32B-2412	xiyansql-qwencoder-32b	xiyansql-qwencoder-3b
chave	a chave de API do provedor de serviços (ex.: OpenAI, Alibaba Cloud)	a chave de API do modelscope	a chave de API via e-mail	""
url	o endpoint do provedor de serviços (ex.: "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 gerais

Se você quiser usar LLMs gerais, ex.: gpt3.5, pode configurar diretamente assim:

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

Se você quiser usar Qwen da Alibaba, ex.: Qwen-max, pode usar a seguinte configuração:

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

Modelo SOTA de Text-to-SQL

Recomendamos o XiYanSQL-qwencoder-32B (https://github.com/XGenerationLab/XiYanSQL-QwenCoder), que é o modelo SOTA em text-to-sql, veja Bird benchmark. Há duas maneiras de usar o modelo. Você pode usar qualquer uma delas. (1) Modelscope, (2) Alibaba Cloud DashScope.

(1) Versão Modelscope

Você precisa solicitar uma key de API-inference do Modelscope, https://www.modelscope.cn/docs/model-service/API-Inference/intro Então você pode usar a seguinte configuração:

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

Leia nossa descrição do modelo para mais detalhes.

(2) Versão Dashscope

Implantamos o modelo no Alibaba Cloud DashScope, então você precisa definir as seguintes variáveis de ambiente: Envie-me seu e-mail para obter o key. ( godot.lzl@alibaba-inc.com ) No e-mail, anexe as seguintes informações:

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

Enviaremos a você um key according to your email. And you can fill the key no arquivo yml. O key expirará em 1 mês ou 200 consultas ou outras restrições legais.

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

Nota: este serviço de modelo é apenas para teste; se você precisar usá-lo em produção, entre em contato conosco.

(3) Versão local

Alternativamente, você também pode implantar o modelo XiYanSQL-qwencoder-32B em seu próprio servidor. Veja Modelo local para mais detalhes.

Configuração do banco de dados

host, port, user, password, database são as informações de conexão do banco de dados.

Você pode usar bancos de dados locais ou remotos. Atualmente suportamos MySQL e PostgreSQL (mais dialetos em breve).

MySQL

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

PostgreSQL

Passo 1: Instale os pacotes Python

pip install psycopg2

Passo 2: prepare o config.yml assim:

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

Observe que dialect should be postgresql para postgresql.

Inicialização

Inicialização do servidor

Se você quiser iniciar o servidor com sse, execute o seguinte comando em um terminal:

YML=path/to/yml python -m xiyan_mcp_server

Então você deve ver as informações em http://localhost:8000/sse no seu navegador. (Padrão, altere se seu servidor mcp rodar em outro host/porta)

Caso contrário, se você usar o protocolo de transporte stdio, normalmente você declara o comando do servidor mcp no aplicativo mcp específico em vez de iniciá-lo em um terminal. No entanto, você ainda pode depurar com este comando se necessário.

Configuração do cliente

Claude Desktop

Adicione isto no arquivo de configuração do Claude Desktop, ref Exemplo de configuração do Claude Desktop

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

Observe que o comando Python aqui requer o caminho completo para o executável Python (/xxx/python); caso contrário, o interpretador Python não pode ser encontrado. Você pode determinar este caminho usando o comando which python. O mesmo se aplica a outros aplicativos.

O Claude Desktop atualmente não suporta o protocolo de transporte SSE.

Cline

Prepare a configuração como Claude Desktop

Goose

Se você usar stdio, adicione o seguinte comando na configuração, ref Exemplo de configuração do Goose

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

Caso contrário, se você usar sse, altere o Tipo para SSE e defina o endpoint para http://127.0.0.1:8000/sse

Cursor

Use o comando semelhante ao seguinte.

Para stdio:

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

Para sse:

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

Witsy

Adicione o seguinte no comando:

/xxx/python -m xiyan_mcp_server

Adicione uma env: a chave é YML e o valor é o caminho para o seu arquivo yml. Ref Exemplo de configuração do Witsy

Entre em contato conosco:

Se você estiver interessado em nossa pesquisa ou produtos, sinta-se à vontade para entrar em contato conosco.

Informações de contato:

Yifu Liu, zhencang.lyf@alibaba-inc.com

Junte-se ao nosso grupo DingTalk

Ding Group钉钉群

Outros links relacionados

Citação

Se você achar nosso trabalho útil, sinta-se à vontade para nos citar.

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