Apifox MCP 服务器
让 AI 助手自动管理你的 Apifox API 文档！
这是一个 Model Context Protocol (MCP) 服务器，允许 Claude Desktop、Claude Code、Cursor 等 MCP 客户端通过 Apifox Open API 自动导入 OpenAPI/Swagger 规范到你的 Apifox 项目。
✨ 主要功能
- ✅ API 导入：批量导入 OpenAPI/Swagger 规范到 Apifox（稳定可靠）
- ✅ API 导出：支持 Summary（目录结构）和 Full（完整规范）两种模式
- ✅ 智能废弃标记：自动检测并标记已删除的接口为废弃状态（v1.2.1）
- ✅ 部分模块导入：支持只导入部分模块，不影响其他模块（智能范围检测）
- ✅ 多格式支持：支持 OpenAPI 3.0/3.1 和 Swagger 2.0
- ✅ 详细统计：完整的导入/导出统计信息和错误报告
🚀 快速开始
1. 安装
方式 1: 使用 npx（推荐）
无需安装，直接使用最新版本：
npx -y apifox-openapi-mcp@latest --token "YOUR_TOKEN" --project-id "YOUR_PROJECT_ID"
方式 2: 本地安装
# 克隆仓库
git clone https://github.com/yourusername/apifox-mcp.git
cd apifox-mcp
# 安装依赖
npm install
# 构建
npm run build
# 本地链接（可选，用于全局使用）
npm link
2. 获取 API Token 和项目 ID
步骤：
- 获取 Token：登录 Apifox → 头像 → 账号设置 → API 访问令牌 → 新建令牌
- 获取 Project ID：打开项目 → 项目设置 → 基本设置 → 复制项目 ID
3. 配置 MCP 客户端
3.1 Claude Desktop
编辑 Claude Desktop 配置文件：
- Linux/Mac:
~/.config/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
方式 1: 使用 npx（推荐，总是使用最新版本）
{
"mcpServers": {
"apifox": {
"command": "npx",
"args": [
"-y",
"apifox-openapi-mcp@latest",
"--token",
"你的-APIFOX-TOKEN",
"--project-id",
"你的-项目-ID"
]
}
}
}
方式 2: 本地安装（使用绝对路径）
{
"mcpServers": {
"apifox": {
"command": "node",
"args": [
"/绝对路径/apifox-mcp/dist/index.js",
"--token",
"你的-APIFOX-TOKEN",
"--project-id",
"你的-项目-ID"
]
}
}
}
方式 3: 使用 npm link 后
{
"mcpServers": {
"apifox": {
"command": "apifox-mcp",
"args": [
"--token",
"你的-APIFOX-TOKEN",
"--project-id",
"你的-项目-ID"
]
}
}
}
3.2 Claude Code
方式 1: 使用 CLI 命令（推荐）
# 添加 MCP 服务器
claude mcp add apifox
# 按提示输入配置
# Command: npx
# Args: -y apifox-openapi-mcp@latest --token "你的-TOKEN" --project-id "你的-项目-ID"
# 验证配置
claude mcp list
方式 2: 直接编辑配置文件
编辑 ~/.config/Claude/claude_desktop_config.json（与 Claude Desktop 共享配置文件）：
{
"mcpServers": {
"apifox": {
"command": "npx",
"args": [
"-y",
"apifox-openapi-mcp@latest",
"--token",
"你的-APIFOX-TOKEN",
"--project-id",
"你的-项目-ID"
]
}
}
}
重启 Claude Code 后生效。
3.3 Cursor
步骤：
- 打开 Cursor 设置：
Cursor Settings>Features>MCP - 点击
+ Add New MCP Server按钮 - 填写配置信息：
- Name:
apifox - Command:
npx - Args:
-y apifox-openapi-mcp@latest --token 你的-APIFOX-TOKEN --project-id 你的-项目-ID - Transport:
stdio
- Name:
- 保存配置
使用提示：
- Cursor 的 Composer Agent 会自动使用 MCP 工具
- 最多支持 40 个 MCP 工具
- 给出明确指令时效果最佳，例如："请使用 Apifox 工具导入这个 API"
4. 重启客户端
完全退出并重新打开对应的 MCP 客户端（Claude Desktop / Claude Code / Cursor），MCP 服务器会自动加载。
📌 版本管理说明
为什么使用 @latest？
- ✅ 总是使用最新版本 - 自动获取最新功能和修复
- ✅ 无需手动更新 - npx 会自动下载最新版本
- ✅ 避免缓存问题 - 配合
-y参数跳过确认
查看当前版本：
# 查看 npx 使用的版本
npx -y apifox-openapi-mcp@latest --version
# 查看 npm 上的最新版本
npm view apifox-openapi-mcp version
# 查看全局安装的版本
npm list -g apifox-openapi-mcp
其他版本管理方式：
-
指定具体版本（适合生产环境）：
"args": ["-y", "apifox-openapi-mcp@1.3.1", ...] -
全局安装（更快的启动速度）：
npm install -g apifox-openapi-mcp然后在配置中使用
"command": "apifox-mcp"
📖 使用方法
在 MCP 客户端中使用
与 AI 助手（Claude Desktop / Claude Code / Cursor）对话，它会自动调用 MCP 工具：
你: 帮我创建一个用户管理 API 并导入到 Apifox
Claude: 好的，我为你创建一个用户管理 API...
[自动生成 OpenAPI 规范]
[自动调用 import_openapi 工具]
✅ OpenAPI 规范导入完成！
📋 接口导入统计：
- 创建: 4
- 更新: 0
- 失败: 0
- 忽略: 0
🎉 成功导入 4 个项！
🔧 可用工具
1. import_openapi - API 导入（推荐）
使用 Apifox Open API 批量导入 OpenAPI/Swagger 规范。稳定可靠，推荐使用。
参数：
spec(必需): OpenAPI/Swagger 规范对象（必须包含openapi/swagger、info、paths字段）options(可选): 导入选项endpointOverwriteBehavior: 接口覆盖行为OVERWRITE_EXISTING(默认): 覆盖现有接口AUTO_MERGE: 自动合并KEEP_EXISTING: 保留现有CREATE_NEW: 创建新接口
schemaOverwriteBehavior: 数据模型覆盖行为（同上）markDeprecatedEndpoints: 自动标记废弃接口（v1.2.1 新增）true: 启用智能废弃标记（强烈推荐）false: 不标记（默认）- 工作原理：
- 导出现有接口
- 智能检测导入范围（如只导入
/api/marketing模块） - 只对比该范围内的接口
- 标记已删除的接口为
deprecated
- 支持部分模块导入，不会误标记其他模块
updateFolderOfChangedEndpoint: 是否更新修改接口的目录（默认：false）prependBasePath: 是否添加basePath前缀到路径（默认：false）targetBranchId: 目标分支 ID（可选，用于多分支项目）
示例 1：基础导入
{
"spec": {
"openapi": "3.0.0",
"info": {
"title": "用户管理 API",
"version": "1.0.0"
},
"paths": {
"/users": {
"get": {
"summary": "获取用户列表",
"tags": ["用户管理"],
"responses": {
"200": {
"description": "成功"
}
}
}
}
}
},
"options": {
"endpointOverwriteBehavior": "OVERWRITE_EXISTING"
}
}
示例 2：启用智能废弃标记（推荐）
{
"spec": {
"openapi": "3.0.0",
"info": {
"title": "营销模块 API",
"version": "2.0.0"
},
"paths": {
"/api/marketing/campaigns": {
"get": {
"summary": "获取营销活动列表",
"tags": ["营销活动"],
"responses": {
"200": {
"description": "成功"
}
}
}
}
}
},
"options": {
"endpointOverwriteBehavior": "OVERWRITE_EXISTING",
"markDeprecatedEndpoints": true
}
}
说明：
- 导入时会自动检测范围为
/api/marketing - 只标记该范围内已删除的接口为废弃
- 不会影响
/api/users、/api/products等其他模块
返回结果：
✅ OpenAPI 规范导入完成！
📋 接口导入统计：
- 创建: 4
- 更新: 0
- 失败: 0
- 忽略: 0
📦 数据模型导入统计：
- 创建: 2
- 更新: 0
- 失败: 0
- 忽略: 0
🎉 成功导入 6 个项！
2. export_openapi - API 导出
从 Apifox 项目导出 OpenAPI/Swagger 规范。AI 可以使用此工具查看现有接口，避免重复创建或参考现有风格。
参数：
mode(可选): 导出模式summary: 仅导出目录结构和接口列表（推荐，节省上下文）full: 导出完整的 OpenAPI 规范（默认）
oasVersion(可选): OpenAPI/Swagger 版本（仅full模式有效）2.0: Swagger 2.03.0: OpenAPI 3.0（默认）3.1: OpenAPI 3.1
exportFormat(可选): 导出格式（仅full模式有效）JSON: JSON 格式（默认）YAML: YAML 格式
pathFilter(可选): 路径过滤器，只导出匹配的接口路径（支持前缀匹配）- 示例：
"/api/user"只导出用户相关接口
- 示例：
示例 1：Summary 模式（推荐）
{
"mode": "summary"
}
返回结果：
✅ 接口文档概览（Summary 模式）
📊 统计信息：
- 项目标题: 我的 API 项目
- 总接口数: 26
📁 目录结构和接口列表：
📂 用户管理
└─ [GET] /api/users
获取用户列表
└─ [POST] /api/users
创建用户
📂 商品管理
└─ [GET] /api/products
获取商品列表
💡 提示：
- 导入新接口时，请参考上述目录结构
- 将相关接口放入对应的目录（使用 tags 字段）
示例 2：Full 模式 + 路径过滤
{
"mode": "full",
"oasVersion": "3.0",
"exportFormat": "JSON",
"pathFilter": "/api/user"
}
返回结果：
✅ OpenAPI 规范导出成功（Full 模式）
📊 导出统计：
- OpenAPI 版本: 3.0.1
- 项目标题: 我的 API 项目
- 接口数量: 2（已按 pathFilter 过滤）
- 数据模型数量: 1
📋 接口列表：
- /api/user [GET, POST]
- /api/user/{id} [GET, PUT, DELETE]
📄 完整 OpenAPI 规范：
{
"openapi": "3.0.1",
"info": {
"title": "我的 API 项目",
"version": "1.0.0"
},
"paths": {
"/api/user": {...},
"/api/user/{id}": {...}
},
"components": {
"schemas": {
"User": {...}
}
}
}
💡 使用场景
场景 1：首次创建 API 文档
你: 帮我创建一个用户管理 API，包括 CRUD 操作
AI: [生成 OpenAPI 规范]
[调用 import_openapi]
✅ 成功创建 4 个接口
场景 2：更新部分模块 + 自动标记废弃接口
你: 更新营销模块 API，移除优惠券接口，改用积分系统
AI: [先调用 export_openapi mode=summary 查看现有结构]
[生成新的营销模块规范]
[调用 import_openapi 并启用 markDeprecatedEndpoints]
🔍 检测到导入范围: /api/marketing
🔖 标记了 1 个废弃接口路径（优惠券相关）
✅ 其他模块（用户、商品）保持不变
场景 3：查看现有接口避免重复
你: 帮我添加商品搜索功能
AI: [先调用 export_openapi mode=summary]
发现项目中已有 /api/products/search 接口
我可以参考现有的接口风格来设计新功能...
📊 API 响应格式
导入成功后会返回详细的统计信息：
{
"data": {
"counters": {
"endpointCreated": 4, // 创建的接口数
"endpointUpdated": 0, // 更新的接口数
"endpointFailed": 0, // 失败的接口数
"endpointIgnored": 0, // 忽略的接口数
"schemaCreated": 2, // 创建的数据模型数
"schemaUpdated": 0, // 更新的数据模型数
"schemaFailed": 0, // 失败的数据模型数
"schemaIgnored": 0 // 忽略的数据模型数
// ... 其他计数
},
"errors": [] // 错误信息（如果有）
}
}
⚙️ 命令行使用
你也可以直接从命令行运行 MCP 服务器：
# 方式 1: 使用命令行参数
node dist/index.js --token "YOUR_TOKEN" --project-id "YOUR_PROJECT_ID"
# 方式 2: 使用环境变量
export APIFOX_TOKEN="YOUR_TOKEN"
export APIFOX_PROJECT_ID="YOUR_PROJECT_ID"
node dist/index.js
# 可选参数
node dist/index.js \
--token "YOUR_TOKEN" \
--project-id "YOUR_PROJECT_ID" \
--base-url "https://api.apifox.com"
🛠 技术栈
- TypeScript - 类型安全的开发
- MCP SDK - Model Context Protocol 实现
- Apifox Open API - 官方 API 接口
- Axios - HTTP 客户端
🔗 关于 Apifox Open API
本项目使用 Apifox Open API 官方接口，经过充分测试，以下功能稳定可用：
| 功能 | API 端点 | 状态 | 说明 |
|---|---|---|---|
| 导入 OpenAPI | POST /v1/projects/{projectId}/import-openapi | ✅ 稳定 | 支持批量导入、覆盖策略、废弃标记 |
| 导出 OpenAPI | POST /v1/projects/{projectId}/export-openapi | ✅ 稳定 | 支持多版本、过滤、格式选择 |
版本支持：
- OpenAPI 3.0.x ✅
- OpenAPI 3.1.x ✅
- Swagger 2.0 ✅
📝 开发
# 安装依赖
npm install
# 开发模式（自动重新编译）
npm run watch
# 构建
npm run build
# 清理构建产物
npm run clean
🐛 故障排除
问题：Claude Desktop 看不到工具
解决方案：
- 检查配置文件路径和格式是否正确
- 确保使用绝对路径
- 完全退出并重启 Claude Desktop（不是最小化）
问题：导入失败
可能原因：
- Token 或项目 ID 不正确
- OpenAPI 规范格式不完整
- 网络连接问题
解决方案：
- 检查 Token 和项目 ID 是否正确
- 验证 OpenAPI 规范是否包含必需字段（openapi/swagger, info, paths）
- 查看错误信息了解具体原因
问题：导入后没有创建任何内容
可能原因：
- 项目中已存在相同的 API（被设置为忽略）
解决方案：
- 修改 API 的路径或名称
- 使用
endpointOverwriteBehavior: "OVERWRITE_EXISTING"选项覆盖现有接口 - 在 Apifox Web 界面检查导入结果
问题：导出失败或返回空数据
可能原因：
- 项目中没有接口
- Token 权限不足
解决方案：
- 检查项目中是否有接口
- 确认 Token 有读取权限
📚 相关文档
📄 许可证
MIT License
🤝 贡献
欢迎提交 Issue 和 Pull Request！
如果你发现了更多可用的 Apifox Open API 端点，欢迎分享。
Made with ❤️ for the Apifox community