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
保存配置

使用提示：

Cursor 的 Composer Agent 会自动使用 MCP 工具
最多支持 40 个 MCP 工具
给出明确指令时效果最佳，例如："请使用 Apifox 工具导入这个 API"

4. 重启客户端

完全退出并重新打开对应的 MCP 客户端（Claude Desktop / Claude Code / Cursor），MCP 服务器会自动加载。

📌 版本管理说明

为什么使用

✅ 总是使用最新版本 - 自动获取最新功能和修复
✅ 无需手动更新 - 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: 不标记（默认）
  - 工作原理：
    1. 导出现有接口
    2. 智能检测导入范围（如只导入 /api/marketing 模块）
    3. 只对比该范围内的接口
    4. 标记已删除的接口为 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.0
- 3.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

Apifox MCP 服务器

✨ 主要功能

🚀 快速开始

1. 安装

方式 1: 使用 npx（推荐）

方式 2: 本地安装

2. 获取 API Token 和项目 ID

3. 配置 MCP 客户端

3.1 Claude Desktop

方式 1: 使用 npx（推荐，总是使用最新版本）

方式 2: 本地安装（使用绝对路径）

方式 3: 使用 npm link 后

3.2 Claude Code

3.3 Cursor

4. 重启客户端

📌 版本管理说明

📖 使用方法

在 MCP 客户端中使用

🔧 可用工具

1. import_openapi - API 导入（推荐）

2. export_openapi - API 导出

💡 使用场景

场景 1：首次创建 API 文档

场景 2：更新部分模块 + 自动标记废弃接口

场景 3：查看现有接口避免重复

📊 API 响应格式

⚙️ 命令行使用

🛠 技术栈

🔗 关于 Apifox Open API

📝 开发

🐛 故障排除

问题：Claude Desktop 看不到工具

问题：导入失败

问题：导入后没有创建任何内容

问题：导出失败或返回空数据

📚 相关文档

📄 许可证

🤝 贡献

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API

1. `import_openapi` - API 导入（推荐）

2. `export_openapi` - API 导出