YApi MCP Bridge

Un servidor YApi basado en Model Context Protocol (MCP) que permite a los clientes de IA compatibles con MCP consultar, buscar, crear y actualizar interfaces de YApi.

Funciones

Actualmente se ofrecen las siguientes herramientas:

El servidor no ofrece herramientas de eliminación para evitar que los clientes de IA ejecuten operaciones irreversibles por error.

Related MCP server: YApi MCP Server

Instalación con npm

No es necesario clonar el repositorio; se puede ejecutar directamente:

npx -y yapi-mcp-bridge

También se puede instalar de forma global:

npm install -g yapi-mcp-bridge
yapi-mcp-bridge

Tras la instalación global, se puede usar el siguiente comando para ver las estadísticas de invocación de herramientas:

yapi-mcp-stats

Instalación desde el código fuente

Requisitos del entorno

• Node.js 18 o superior

• Una instancia de YApi accesible

• Una cookie de YApi con permisos de acceso al proyecto correspondiente

Para ejecutar desde el código fuente también se necesita pnpm 10 o superior. En macOS se puede instalar Node.js y pnpm con Homebrew:

brew install node pnpm

Instalar dependencias

Tras entrar en el directorio del proyecto, ejecutar:

pnpm install

Configurar YApi

Copiar el ejemplo de variables de entorno:

cp .env.example .env

Editar .env:

YAPI_HOST=https://yapi.example.com
YAPI_COOKIE=_yapi_token=xxx;_yapi_uid=xx;

Descripción de parámetros:

• YAPI_HOST: dirección del servicio YApi; solo se indica el protocolo y el dominio, sin incluir /api.

• YAPI_COOKIE: cadena de cookie completa utilizada al acceder a YApi.

• YAPI_LOG_FILE: ruta opcional del archivo de registro; el valor predeterminado es ~/.yapi-mcp/logs/yapi-mcp.log.

Tras iniciar sesión en YApi, se puede seleccionar cualquier solicitud de YApi en el panel Network de las herramientas de desarrollo del navegador y copiar la Cookie desde los Request Headers. La cookie equivale a una credencial de inicio de sesión; no debe enviarse a Git ni compartirse con otras personas. Este proyecto ya ignora .env de forma predeterminada.

Iniciar el servidor

Ejecutar en el directorio raíz del proyecto:

pnpm start

Este es un servidor MCP stdio. Al iniciarlo directamente no hay una página HTTP normal ni se muestran indicaciones interactivas; espera a que el cliente MCP se comunique a través de la entrada y salida estándar.

Tras un inicio correcto, el servidor emite información similar por stderr, sin contaminar el stdout utilizado para la comunicación MCP:

[yapi-mcp] server started (stdio), tools=9, log=~/.yapi-mcp/logs/yapi-mcp.log

Ejecutar las pruebas:

pnpm test

Conexión con clientes MCP

Al usar el paquete npm, añadir la siguiente configuración en un cliente compatible con servidores MCP stdio:

{
  "mcpServers": {
    "yapi": {
      "command": "npx",
      "args": [
        "-y",
        "yapi-mcp-bridge"
      ],
      "env": {
        "YAPI_HOST": "https://yapi.example.com",
        "YAPI_COOKIE": "_yapi_token=xxx;_yapi_uid=xx;"
      }
    }
  }
}

Si se inicia desde el código fuente, se puede seguir usando la configuración con la ruta absoluta de Node.js:

{
  "command": "node",
  "args": ["/absolute/path/to/yapi-mcp-server/src/index.js"],
  "env": {
    "YAPI_HOST": "https://yapi.example.com",
    "YAPI_COOKIE": "_yapi_token=xxx;_yapi_uid=xx;"
  }
}

Tras modificar la configuración, reiniciar o recargar el cliente MCP. El cliente debería detectar 9 herramientas que comienzan con yapi_.

Uso

Tras la conexión, se puede indicar directamente al cliente de IA que opere con YApi en lenguaje natural.

Consultar proyectos e interfaces

获取 YApi 项目 1922 的详情。

列出 YApi 项目 1922 的所有接口分类。

在 YApi 项目 1922 中搜索路径包含 /order 的接口，并获取匹配接口的常用定义。

yapi_get_interface devuelve por defecto solo la siguiente información habitual:

• ID de la interfaz, título, método HTTP y ruta

• Descripción de la interfaz

• Parámetros de entrada Path, Query, Header y Body

• Tipo de respuesta y contenido de la respuesta

Cuando sea necesario revisar los metadatos de YApi u obtener la respuesta original, se puede solicitar explícitamente el uso de full: true:

获取 YApi 接口 5001 的原始全量数据。

Crear categorías de interfaces

在 YApi 项目 1922 中创建一个名为“订单管理”的接口分类。

Crear interfaces

在 YApi 项目 1922、分类 3001 中创建接口：
标题为“创建订单”，方法为 POST，路径为 /orders，
请求体类型为 JSON，请求示例为 {"productId": 1001, "quantity": 2}，
响应示例为 {"id": 9001, "status": "created"}。

Parámetros obligatorios al crear una interfaz:

requestBody y responseBody deben pasarse como cadenas. Si el contenido es JSON o JSON Schema, también debe serializarse primero como cadena.

Actualizar interfaces

把 YApi 接口 5001 的标题修改为“查询订单详情”，状态修改为 done，并添加 order 标签。

Para actualizar una interfaz solo es necesario proporcionar el ID de la interfaz y los campos que se desean modificar; los campos no proporcionados no se envían a YApi.

Registro y estadísticas de invocación

El servidor escribe el registro por defecto en:

~/.yapi-mcp/logs/yapi-mcp.log

El registro utiliza el formato JSON Lines, con un evento por línea. Por ejemplo:

{"timestamp":"2026-08-21T08:00:00.000Z","event":"tool_call","tool":"yapi_get_interface","status":"success","durationMs":128}

El registro de herramientas solo incluye el nombre de la herramienta, el estado de la invocación y el tiempo empleado; no registra parámetros de invocación, contenido de interfaces, cookies ni otras credenciales.

Si el registro supera las 1000 entradas al añadir nuevas, el servidor elimina automáticamente las 300 más antiguas para evitar que el archivo de registro crezca indefinidamente.

Ver la frecuencia de invocación de herramientas, el número de aciertos, el número de fallos y el tiempo medio:

# 全局安装
yapi-mcp-stats

# 从源码运行
pnpm stats

La ubicación del registro se puede modificar mediante YAPI_LOG_FILE. Al usar una ruta relativa, se resuelve respecto al directorio de inicio del servidor; en los clientes MCP se recomienda configurar una ruta absoluta.

Preguntas frecuentes

Devuelve "Inicie sesión" o no tiene permisos

Comprobar lo siguiente:

• Si YAPI_COOKIE está completa y no ha caducado.

• Si el usuario correspondiente a la cookie actual tiene permisos de acceso o edición del proyecto.

• Si se ha reiniciado el servidor MCP tras modificar la cookie.

El cliente no encuentra el servidor

• Confirmar que src/index.js en la configuración MCP usa una ruta absoluta.

• Confirmar que command apunta a un Node.js ejecutable.

• Ejecutar pnpm test en el directorio del proyecto para confirmar que las dependencias y el entorno de ejecución funcionan correctamente.

Los cambios en .env no surten efecto

.env se carga por defecto desde el directorio de trabajo actual del servidor. Al iniciar desde la terminal, ejecutar pnpm start en el directorio raíz del proyecto; al iniciar desde un cliente MCP, se recomienda pasar explícitamente YAPI_HOST y YAPI_COOKIE mediante env en la configuración.

Estructura del proyecto

src/
├── handlers/       # MCP 工具 handler 与 YApi 方法映射
├── tools/          # 工具定义、Zod 输入输出 Schema
├── index.js        # stdio Server 入口
├── server.js       # McpServer 注册
└── yapi.js         # YApi HTTP API 封装
test/               # 单元测试与 MCP 注册测试

Aviso de seguridad

• No enviar .env ni cookies de YApi.

• Las herramientas de escritura modifican realmente los datos de YApi; antes de ejecutarlas se debe confirmar el ID del proyecto, el ID de la categoría y el ID de la interfaz.

• Se recomienda usar una cuenta de YApi con el menor ámbito de permisos posible.

• El registro se guarda por defecto en .yapi-mcp/logs/ dentro del directorio del usuario; no se escribe en el directorio de instalación de npm.