YAPI MCP PRO

一个功能强大的 Model Context Protocol (MCP) 服务器，专为 YApi 接口管理平台设计。支持在 Cursor、Claude Desktop 等 AI 编辑器中直接操作 YApi，提供完整的接口生命周期管理功能。

# 1. 检查版本命令是否正常 npx yapi-mcp-pro --version # 2. 如果上面命令没有正常输出版本号，执行清缓存： npm cache clean --force # 3. 然后重新测试 npx yapi-mcp-pro --version

- ✅正常：显示版本号如0.2.1
- ❌异常：显示错误信息、找不到命令、或者卡住不动

💡为什么会出现这个问题？NPM缓存可能损坏或过期，导致无法正确下载或运行包。清理缓存可以解决大部分连接问题。

# 清理NPM缓存并重新安装 npm cache clean --force && npx clear-npx-cache 2>/dev/null || true # 验证安装 npx yapi-mcp-pro --version # 测试YApi连接（替换为您的实际地址） curl -I "http://your-yapi-server.com"

📦自动更新：使用npx -y yapi-mcp-pro确保总是使用最新版本
- 📥 安装Node.js→点击查看详细安装指南
- 🔧 配置Cursor→继续下面的配置步骤
- 🎉 开始使用→测试连接和使用

_yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...(您的完整token); _yapi_uid=您的用户ID; keep-alive

# 创建目录和文件 mkdir -p .cursor touch .cursor/mcp.json # 然后编辑文件内容

{ "mcpServers": { "yapi-mcp-pro": { "command": "npx", "args": ["-y", "yapi-mcp-pro"], "env": { "YAPI_BASE_URL": "http://your-yapi-server.com", "YAPI_TOKEN": "_yapi_token=您的真实token; _yapi_uid=您的用户ID", "NODE_ENV": "cli" } } } }

{ "mcpServers": { "yapi-mcp-pro": { "command": "npx", "args": ["-y", "yapi-mcp-pro"], "env": { "YAPI_BASE_URL": "http://your-yapi-server.com", "YAPI_TOKEN": "_yapi_token=您的真实token值; _yapi_uid=您的用户ID", "NODE_ENV": "cli" } } } }

- macOS:~/Library/Application Support/Cursor/User/settings.json
- Windows:%APPDATA%\Cursor\User\settings.json
- Linux:~/.config/Cursor/User/settings.json
- 重启Cursor- 让MCP配置生效
- 测试连接- 在Cursor中输入以下命令测试：

- 检查YAPI_BASE_URL是否正确
- 确保网络能访问YApi服务器
- 验证YApi服务器是否正常运行

- 确认已重启Cursor
- 检查配置文件路径和格式是否正确
- 查看Cursor的MCP连接状态

- 如果显示版本号（如v18.17.0），说明已安装
- 如果提示 "command not found" 或类似错误，需要安装
- 打开浏览器，访问https://nodejs.org/
- 页面会自动识别您的操作系统
- 点击绿色的"Download Node.js (LTS)"按钮
- 双击下载的.msi文件
- 点击 "Next" 接受许可协议
- 选择安装路径（建议使用默认路径）
- 重要：确保勾选 "Add to PATH" 选项
- 点击 "Install" 开始安装
- 安装完成后重启命令提示符
- 双击下载的.pkg文件
- 按照安装向导提示操作
- 输入管理员密码（如果需要）
- 安装完成后重启终端

# 下载并解压（以Ubuntu为例） wget https://nodejs.org/dist/v18.17.0/node-v18.17.0-linux-x64.tar.xz tar -xf node-v18.17.0-linux-x64.tar.xz # 移动到系统目录 sudo mv node-v18.17.0-linux-x64 /opt/nodejs # 创建软链接 sudo ln -s /opt/nodejs/bin/node /usr/local/bin/node sudo ln -s /opt/nodejs/bin/npm /usr/local/bin/npm sudo ln -s /opt/nodejs/bin/npx /usr/local/bin/npx

# 首先安装Chocolatey (如果没有) Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1')) # 安装Node.js choco install nodejs # 验证安装 node --version npm --version

# 首先安装Homebrew (如果没有) /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # 安装Node.js brew install node # 验证安装 node --version npm --version

# Ubuntu/Debian sudo apt update sudo apt install nodejs npm # CentOS/RHEL (使用dnf) sudo dnf install nodejs npm # CentOS/RHEL (使用yum) sudo yum install nodejs npm # Arch Linux sudo pacman -S nodejs npm # 验证安装 node --version npm --version

# 检查Node.js版本（应显示 v16.0.0 或更高版本） node --version # 检查npm版本（应显示 7.0.0 或更高版本） npm --version # 检查npx是否可用 npx --version # 测试npm连接（可选） npm ping

- node --version显示版本号（如：v18.17.0）
- npm --version显示版本号（如：9.6.7）
- npx --version显示版本号（如：9.6.7）

- Windows: 重启命令提示符，或检查环境变量PATH
- macOS/Linux: 重启终端，或手动添加到PATH：

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc source ~/.bashrc

# 更新到最新版本 npm install -g npm@latest # 或重新下载安装最新版Node.js

# macOS/Linux: 修复npm权限 sudo chown -R $(whoami) ~/.npm sudo chown -R $(whoami) /usr/local/lib/node_modules

# 切换到国内镜像源 npm config set registry https://registry.npmmirror.com # 验证镜像源 npm config get registry

# 设置npm全局安装目录（避免权限问题） mkdir ~/.npm-global npm config set prefix '~/.npm-global' # 添加到环境变量（macOS/Linux） echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile source ~/.profile # Windows用户需要手动添加 %USERPROFILE%\.npm-global 到PATH环境变量

# 测试YApi MCP Pro是否可以正常运行 npx -y yapi-mcp-pro --help # 如果看到帮助信息，说明环境配置成功！

选项： --version 显示版本号 --yapi-base-url YApi服务器基础URL --yapi-token YApi服务器授权Token --help 显示帮助信息

# Windows (PowerShell) echo "=== YApi MCP Pro 环境检查 ===" && echo "Node.js版本:" && node --version && echo "NPM版本:" && npm --version && echo "网络连通性:" && npm ping # macOS/Linux echo "=== YApi MCP Pro 环境检查 ===" && echo "Node.js版本:" && node --version && echo "NPM版本:" && npm --version && echo "测试NPM连接:" && npm ping # 检查NPX可用性 npx --version

- 访问nodejs.org下载安装最新LTS版本
- 或使用包管理器：

# macOS (使用Homebrew) brew install node # Ubuntu/Debian sudo apt update && sudo apt install nodejs npm # Windows (使用Chocolatey) choco install nodejs

# 重新安装NPM (NPX包含在NPM中) npm install -g npm@latest # 或单独安装NPX npm install -g npx

# macOS/Linux: 修复NPM权限 sudo chown -R $(whoami) ~/.npm sudo chown -R $(whoami) /usr/local/lib/node_modules # 或配置NPM使用不同目录 npm config set prefix ~/.npm-global export PATH=~/.npm-global/bin:$PATH

# 检查NPM Registry连接 npm config get registry # 切换到国内镜像（如果在中国） npm config set registry https://registry.npmmirror.com # 测试网络连接 curl -I https://registry.npmjs.org

# 安装Node.js (推荐使用Homebrew) brew install node # 验证安装 node --version && npm --version

# 创建配置目录 mkdir -p ~/.config/Cursor/User # 编辑配置文件 code ~/.config/Cursor/User/settings.json # 或使用任意文本编辑器

# 使用官方安装器 # 访问 https://nodejs.org/ 下载Windows安装包 # 或使用Chocolatey choco install nodejs # 验证安装 node --version; npm --version

# 打开配置目录 explorer %APPDATA%\Cursor\User\ # 编辑settings.json文件 # 如果文件不存在，创建它

# Ubuntu/Debian sudo apt update sudo apt install nodejs npm # CentOS/RHEL/Fedora sudo dnf install nodejs npm # Fedora sudo yum install nodejs npm # CentOS/RHEL # Arch Linux sudo pacman -S nodejs npm # 验证安装 node --version && npm --version

# 创建配置目录 mkdir -p ~/.config/Cursor/User # 编辑配置文件 nano ~/.config/Cursor/User/settings.json # 或使用您喜欢的编辑器

- ⚡ 5分钟快速开始-推荐先看这里
- ✨ 核心特性
- 🎯 支持的AI编辑器
- 🔧 详细配置指南
- 📚 MCP工具详解
- 💡 使用示例
- 🛠️ 项目管理
- 🔍 故障排除
- 📖 高级用法
- 🤝 贡献指南

# 全局安装 npm install -g yapi-mcp # 或使用pnpm pnpm add -g yapi-mcp

# 克隆项目 git clone https://github.com/your-username/yapi-mcp.git cd yapi-mcp # 安装依赖 npm install # 或使用 pnpm (推荐) pnpm install # 构建项目 npm run build

# 1. 复制配置模板 cp .env.example .env # 2. 编辑配置文件（选择您喜欢的编辑器） vim .env # 或者 nano .env # 或者 code .env

# === 必填项 === YAPI_BASE_URL=http://your-yapi-server.com # 替换为您的YApi服务器地址 YAPI_TOKEN=your_auth_token # 替换为您的认证信息（见下方获取方法） # === 可选项（有默认值）=== PORT=3388 # MCP服务端口，默认3388 YAPI_CACHE_TTL=10 # 缓存时间（分钟），默认10分钟 YAPI_LOG_LEVEL=info # 日志级别，默认info

# Token认证示例 # 格式：项目ID:项目Token,项目ID:项目Token YAPI_TOKEN=PROJECT_ID_1:your_project_token_1,PROJECT_ID_2:your_project_token_2 # 单个项目示例 YAPI_TOKEN=PROJECT_ID:your_project_token

# ================================ # YAPI MCP PRO 配置文件 # ================================ # ⚠️ 重要：此文件包含敏感信息，不要提交到Git仓库！ # === 基础配置（必填）=== YAPI_BASE_URL=http://yapi.yourcompany.com YAPI_TOKEN=_yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; _yapi_uid=1234 # === 服务配置（可选）=== PORT=3388 YAPI_CACHE_TTL=10 YAPI_LOG_LEVEL=info # === 高级配置（可选）=== # YAPI_GROUP_ID=YOUR_GROUP_ID # 默认分组ID（创建项目时使用） # YAPI_ENABLE_CACHE=true # 是否启用缓存，默认true

# 使用项目管理脚本（推荐） ./start-mcp.sh start # 或手动启动 npm run dev

# Token认证配置 YAPI_BASE_URL=http://your-yapi-server.com YAPI_TOKEN=PROJECT_ID:YOUR_PROJECT_TOKEN,ANOTHER_PROJECT_ID:ANOTHER_TOKEN

{ "mcpServers": { "yapi-mcp-pro": { "command": "npx", "args": ["-y", "yapi-mcp-pro"], "env": { "YAPI_BASE_URL": "http://your-yapi-server.com", "YAPI_TOKEN": "_yapi_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...; _yapi_uid=YOUR_USER_ID", "NODE_ENV": "cli", "YAPI_LOG_LEVEL": "info", "YAPI_CACHE_TTL": "10" } } } }

- ✅ 性能更好，减少启动时间
- ✅ 支持实时数据推送
- ✅ 便于调试和开发
- ✅ 支持多客户端共享

# 启动服务 ./start-mcp.sh start # 检查状态 ./start-mcp.sh status

{ "mcpServers": { "yapi-mcp-pro": { "url": "http://localhost:3388/sse" } } }

{ "mcpServers": { "yapi-mcp-pro": { "command": "node", "args": ["/path/to/yapi-mcp/dist/index.js"], "env": { "YAPI_BASE_URL": "http://your-yapi-server.com", "YAPI_TOKEN": "your_token" } } } }

{ "mcpServers": { "yapi-mcp-pro": { "command": "node", "args": ["/path/to/yapi-mcp/dist/index.js"], "env": { "YAPI_BASE_URL": "http://your-yapi-server.com", "YAPI_TOKEN": "your_token" } } } }

# 测试连接 请获取我的YApi用户信息 # 测试项目列表 请列出所有YApi项目 # 测试接口搜索 请搜索用户相关的接口

- projectId(string): 项目ID
- apiId(string): 接口ID

- 接口基本信息（名称、路径、方法）
- 请求参数（URL参数、查询参数、请求头、请求体）
- 响应信息（响应类型、响应内容）
- 接口文档和描述

- projectId(string): 项目ID
- catid(string): 分类ID
- title(string): 接口标题
- path(string): 接口路径
- method(string): 请求方法
- id(string, 可选): 接口ID（更新时必填）
- desc(string, 可选): 接口描述
- req_(可选): 各种请求参数配置
- res_(可选): 响应配置

- nameKeyword(string, 可选): 接口名称关键字
- pathKeyword(string, 可选): 接口路径关键字
- projectKeyword(string, 可选): 项目关键字
- limit(number, 可选): 返回结果数量限制

- interfaceId(string): 接口ID
- projectId(string): 项目ID

- interfaceId(string): 源接口ID
- projectId(string): 项目ID
- catId(string, 可选): 目标分类ID