Apifox Filter MCP Server

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

支持两种数据源模式：

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

功能特点

🎯 精准过滤 - 根据 URL 模式搜索接口，支持通配符和模糊匹配
🧠 智能搜索 - 支持自然语言查询，自动提取关键词并按相关度排序
📁 文件夹检索 - 支持按 Apifox 文件夹目录浏览和筛选接口
📦 按需获取 - 只获取需要的接口详情，最小化上下文占用
🏷️ 标签筛选 - 支持按标签分类获取接口列表
⚡ 智能缓存 - 本地 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 中。

Antigravity 配置

CACHE_DIR 必须配置，否则会报错在 Antigravity 环境中获取不到项目目录

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

环境变量

变量	说明	默认值
`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

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

可用工具

smart_search_api（推荐）

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

核心能力：

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

中英文关键词映射示例：

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

评分权重：

匹配类型	权重
路径直接匹配	+15
路径关键词匹配	+10
名称匹配	+8
文件夹匹配	+7
标签匹配	+5
描述匹配	+3

search_api

根据 URL 模式搜索接口。

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

get_api_detail

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

list_api_by_tag

按标签筛选接口列表。

list_api_by_folder

按 Apifox 文件夹路径筛选接口列表，支持精确和模糊匹配（仅 Apifox 模式）。

list_api_folders

列出所有 Apifox 接口文件夹目录结构（仅 Apifox 模式）。

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="用户管理"

按文件夹获取接口

# 查看所有文件夹目录
list_api_folders

# 按文件夹筛选（支持模糊匹配）
list_api_by_folder folder="用户管理"
list_api_by_folder folder="用户管理/登录注册"

本地测试

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:

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

获取 Access Token:

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

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

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
src		src
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts

Folders and files

Latest commit

History

Repository files navigation

Apifox Filter MCP Server

功能特点

配置

配置模式

Apifox 模式配置

最小配置

URL 模式配置

HTTP 示例

本地文件示例

Windows 本地文件

windows

最小配置

Antigravity 配置

环境变量

命令行参数

多模块和分支支持

获取 Apifox Access Token

可用工具

smart_search_api（推荐）

search_api

get_api_detail

list_api_by_tag

list_api_by_folder

list_api_folders

batch_get_apis

list_all_endpoints

refresh_cache

使用示例

智能搜索（自然语言）

搜索用户相关接口

获取特定接口详情

按标签获取接口

按文件夹获取接口

本地测试

1. 构建项目

2. 配置 MCP

3. 获取 Apifox 配置信息

4. 重启 Claude Code

开发

技术栈

许可证

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages