Apifox Filter MCP Server

一个 MCP (Model Context Protocol) Server，用于从 Apifox 精准过滤和获取 API 文档，解决官方 MCP Server 加载全量接口导致的上下文膨胀问题。

支持两种数据源模式：

• Apifox 模式：通过 Apifox API Token 获取项目接口文档
• URL 模式：直接从任意 OpenAPI URL 获取接口文档（无需 Apifox 认证）

功能特点

• 🎯 精准过滤 - 根据 URL 模式搜索接口，支持通配符和模糊匹配
• 🧠 智能搜索 - 支持自然语言查询，自动提取关键词并按相关度排序
• 📦 按需获取 - 只获取需要的接口详情，最小化上下文占用
• 🏷️ 标签筛选 - 支持按标签分类获取接口列表
• ⚡ 智能缓存 - 本地 JSON 缓存，支持定时刷新和 Miss 时自动刷新
• 🔄 批量操作 - 支持批量获取多个接口详情

配置

配置模式

本工具支持两种互斥的配置模式：

| 模式 | 必需配置 | 可选配置 | |------|----------|----------| | Apifox 模式 | APIFOX_ACCESS_TOKEN + projectId | moduleIds, branchId | | URL 模式 | openapiUrl | 无 |

注意：如果同时提供了 openapiUrl 和 Apifox 配置，URL 模式优先。

Apifox 模式配置

最小配置

{
  "mcpServers": {
    "apifox-filter": {
      "command": "npx",
      "args": [
        "-y",
        "apifox-filter-mcp-server@latest",
        "--project-id=<your-project-id>"
      ],
      "env": {
        "APIFOX_ACCESS_TOKEN": "<your-access-token>"
      }
    }
  }
}

{
  "mcpServers": {
    "apifox-filter": {
      "command": "npx",
      "args": [
        "-y",
        "apifox-filter-mcp-server@latest",
        "--project-id=<your-project-id>",
        "--branch-id=<branch-id>",
        "--module-ids=<module-id-1>,<module-id-2>"
      ],
      "env": {
        "APIFOX_ACCESS_TOKEN": "<your-access-token>"
      }
    }
  }
}

URL 模式配置

适用于从 Apifox 本地服务或任意 OpenAPI URL 获取接口文档（解决 Apifox 只有只读权限用户和非 Apifox 用户使用）

支持的协议：

• http:// / https:// - 通过 HTTP 请求获取
• file:// - 直接读取本地文件

HTTP 示例

{
  "mcpServers": {
    "apifox-filter": {
      "command": "npx",
      "args": [
        "-y",
        "apifox-filter-mcp-server@latest",
        "--openapi-url=http://127.0.0.1:4523/export/openapi/11?version=3.0"
      ]
    }
  }
}

本地文件示例

{
  "mcpServers": {
    "apifox-filter": {
      "command": "npx",
      "args": [
        "-y",
        "apifox-filter-mcp-server@latest",
        "--openapi-url=file:///Users/xiaou/project/openapi.json"
      ]
    }
  }
}

Windows 本地文件

{
  "mcpServers": {
    "apifox-filter": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "apifox-filter-mcp-server@latest",
        "--openapi-url=file:///D:/project/openapi.json"
      ]
    }
  }
}

或使用环境变量：

{
  "mcpServers": {
    "apifox-filter": {
      "command": "npx",
      "args": ["-y", "apifox-filter-mcp-server@latest"],
      "env": {
        "OPENAPI_URL": "http://127.0.0.1:4523/export/openapi/11?version=3.0"
      }
    }
  }
}

windows

最小配置

{
  "mcpServers": {
    "apifox-filter": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "apifox-filter-mcp-server@latest",
        "--project-id=<your-project-id>",
      ],
      "env": {
        "APIFOX_ACCESS_TOKEN": "<your-access-token>"
      }
    }
  }
}

{
  "mcpServers": {
    "apifox-filter": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "apifox-filter-mcp-server@latest",
        "--project-id=<your-project-id>",
        "--branch-id=<branch-id>",
        "--module-ids=<module-id-1>,<module-id-2>"
      ],
      "env": {
        "APIFOX_ACCESS_TOKEN": "<your-access-token>"
      }
    }
  }
}

缓存位置说明： 设置 PROJECT_DIR 后，缓存文件会自动存放在 ${PROJECT_DIR}/.apifox-cache/ 目录下。 建议将 .apifox-cache 添加到项目的 .gitignore 中。

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | OPENAPI_URL | OpenAPI 文档 URL（URL 模式） | - | | APIFOX_ACCESS_TOKEN | Apifox 访问令牌（Apifox 模式必填） | - | | APIFOX_PROJECT_ID | 项目 ID（也可通过命令行参数指定） | - | | APIFOX_MODULE_IDS | 模块 ID 列表（逗号分隔）| - | | APIFOX_BRANCH_ID | 分支 ID | - | | APIFOX_API_BASE | Apifox API 基础地址（私有部署时使用） | https://api.apifox.com | | PROJECT_DIR | 用户项目目录（缓存将放在此目录下） | 当前工作目录 | | CACHE_DIR | 缓存目录（覆盖默认位置） | ${PROJECT_DIR}/.apifox-cache | | REFRESH_INTERVAL | 定时刷新间隔（分钟），0 禁用 | 30 | | REFRESH_ON_MISS | 找不到时自动刷新 | true | | MISS_REFRESH_COOLDOWN | 自动刷新冷却（秒） | 60 |

命令行参数

| 参数 | 说明 | |------|------| | --openapi-url=<url> | OpenAPI 文档 URL（URL 模式） | | --project-id=<id> | Apifox 项目 ID | | --module-ids=<id1,id2> | 模块 ID 列表（逗号分隔） | | --branch-id=<id> | 分支 ID |

多模块和分支支持

如果你的 Apifox 项目使用了多模块或分支功能，可以通过以下参数指定：

• --branch-id=<id> 或 APIFOX_BRANCH_ID: 指定分支 ID，默认导出主分支
• --module-ids=<id1,id2,...> 或 APIFOX_MODULE_IDS: 指定模块 ID 列表（逗号分隔），默认导出默认模块

不同的 moduleIds 和 branchId 组合会缓存到不同的文件，互不影响。

获取 Apifox Access Token

1. 登录 Apifox
2. 进入 账户设置 → API 访问令牌
3. 创建新的访问令牌

可用工具

smart_search_api（推荐）

根据自然语言描述智能搜索接口，AI 的首选搜索工具。

核心能力：

• 自动提取中英文关键词并映射到接口路径
• 支持中英文混合查询
• 按相关度评分排序返回结果

中英文关键词映射示例： | 中文 | 映射英文 | |------|----------| | 达人 | daren, influencer, kol | | 列表 | list, page | | 登录 | login, auth, sign-in | | 用户 | user, member, account | | 订单 | order | | 商品 | product, goods, item |

评分权重： | 匹配类型 | 权重 | |---------|------| | 路径直接匹配 | +15 | | 路径关键词匹配 | +10 | | 名称匹配 | +8 | | 标签匹配 | +5 | | 描述匹配 | +3 |

search_api

根据 URL 模式搜索接口。

支持的匹配模式：
- 精确匹配: /api/users
- 通配符: /api/users/*
- 多级通配符: /api/**
- 模糊搜索: users

get_api_detail

获取单个接口的完整文档，包括参数、请求体、响应等详细信息。

list_api_by_tag

按标签筛选接口列表。

batch_get_apis

批量获取多个接口的详细信息。

list_all_endpoints

列出所有接口的路径和方法（仅返回摘要信息）。

refresh_cache

手动刷新接口缓存，从 Apifox 重新获取最新数据。

使用示例

智能搜索（自然语言）

# 搜索达人相关接口
smart_search_api query="达人管理"

# 搜索平台列表接口
smart_search_api query="获取平台列表"

# 中英文混合查询
smart_search_api query="influencer 详情"

返回示例：

{
  "query": "达人平台列表",
  "count": 3,
  "endpoints": [
    {
      "path": "/daren/influencer-info/platform-list",
      "method": "GET",
      "name": "获取平台枚举列表",
      "score": 38,
      "matchReason": "路径匹配: daren; 路径匹配: platform; 路径匹配: list"
    }
  ]
}

搜索用户相关接口

search_api pattern="/api/users/*"

获取特定接口详情

get_api_detail path="/api/users/{id}" method="GET"

按标签获取接口

list_api_by_tag tag="用户管理"

本地测试

1. 构建项目

npm install
npm run build

2. 配置 MCP

在你的 MCP 配置文件中添加以下配置（根据你使用的工具选择配置文件位置）：

Claude Code (claude_desktop_config.json):

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

本地测试配置：

{
  "mcpServers": {
    "apifox-filter": {
      "command": "node",
      "args": [
        "D:/code/apifox-filter-mcp-server/dist/index.js",
        "--project-id=<your-project-id>"
      ],
      "env": {
        "APIFOX_ACCESS_TOKEN": "<your-access-token>"
      }
    }
  }
}

注意：将 D:/code/apifox-filter-mcp-server 替换为你的实际项目路径，<your-project-id> 和 <your-access-token> 替换为真实值。

3. 获取 Apifox 配置信息

获取 Project ID:

1. 登录 Apifox，打开你的项目
2. 在项目设置或 URL 中可以找到项目 ID（通常是一个数字）

获取 Access Token:

1. 登录 Apifox
2. 点击右上角头像 → 账号设置
3. 选择 API 访问令牌
4. 创建新的访问令牌

4. 重启 Claude Code

配置完成后，重启 Claude Code 使配置生效。

开发

# 安装依赖
npm install

# 开发模式（监听文件变化）
npm run dev

# 构建
npm run build

# 类型检查
npm run typecheck

技术栈

• TypeScript
• @modelcontextprotocol/sdk - MCP 官方 SDK
• undici - HTTP 客户端
• tsup - 构建工具

许可证

MIT