接口狐-MCP

Name: 接口狐-MCP
Author: Warren-W

作者：Warren-W2 星标更新：2025-10-23

安装使用来源：spider==github.com

项目介绍

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 服务器会自动加载。

📌 版本管理说明

为什么使用 @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: 不标记（默认）
  - 工作原理：
    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 ✅

接口狐-MCP

项目介绍

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

📝 开发

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

2. `export_openapi` - API 导出