Api Testing MCP

@cocaxcode/api-testing-mcp

最全面的 API 测试 MCP 服务。就是这样。
42 个 MCP 工具 · 零配置 · 适用于任何 MCP 客户端

概览 · 直接对话即可 · 安装 · 功能 · 工具参考 · 存储 · 架构

快速概览

最全面的 API 测试 MCP 服务——42 个工具、零配置，没有其他产品能与之媲美。它不只是一个请求发送器，而是一套完整的测试工作台：支持断言的 HTTP 请求、多步骤流程与变量提取、导入 OpenAPI 并生成感知架构的模拟数据、提供百分位指标的负载测试、跨环境响应差异比较、批量测试运行器、可复用集合、支持目录范围限定和持久化默认值的环境组、Postman 导入/导出，以及 cURL 导出。所有操作都能通过自然对话完成。无需账户、无需云服务、无需生成文件。一切都以内联方式运行，并以纯 JSON 格式存储，由你掌控。

直接对话即可

你无需学习工具名称或参数。描述你的需求，AI 就会选择合适的工具。

"Create a group called my-project and add this directory as scope"
"Set up a dev environment with BASE_URL http://localhost:3000"
"Switch to prod for this session"
"Set dev as the default environment"
"Import my API spec from /api-docs-json"
"Show me all user endpoints"
"GET /users"
"Create a user with random data"
"Verify that DELETE /users/5 returns 204"
"Login as admin, extract the token, then fetch dashboard stats"
"How fast is /health with 50 concurrent requests?"
"Run all my saved smoke tests"
"Compare the users endpoint between dev and prod"
"Export the create-user request as curl"
"Export my collection to Postman"

如果你已导入 OpenAPI 规范，AI 就已了解每个端点、每个必填字段和每个有效枚举值。当你说“创建一篇博客文章”时，它会读取架构并正确构造请求，无需猜测。

安装

Claude Code

claude mcp add --scope user api-testing -- npx -y @cocaxcode/api-testing-mcp@latest

Claude Desktop

将以下内容添加到配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，Windows 上为 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "api-testing": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/api-testing-mcp@latest"]
    }
  }
}

Cursor / Windsurf

将以下内容添加到项目根目录下的 .cursor/mcp.json 或 .windsurf/mcp.json：

{
  "mcpServers": {
    "api-testing": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/api-testing-mcp@latest"]
    }
  }
}

{
  "servers": {
    "api-testing": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/api-testing-mcp@latest"]
    }
  }
}

codex mcp add api-testing -- npx -y @cocaxcode/api-testing-mcp@latest

[mcp_servers.api-testing]
command = "npx"
args = ["-y", "@cocaxcode/api-testing-mcp@latest"]

{
  "mcpServers": {
    "api-testing": {
      "command": "npx",
      "args": ["-y", "@cocaxcode/api-testing-mcp@latest"]
    }
  }
}

快速开始

安装完成后，设置一个环境，以便自动解析相对路径：

"Create an environment called dev with BASE_URL http://localhost:3000"

如果你的 API 有 Swagger/OpenAPI 规范，请将其导入：

"Import my API spec from http://localhost:3000/api-docs-json"

通过以下指令验证：“列出我的环境”——你应该能看到刚刚创建的环境。

功能

HTTP 请求

发送任意 HTTP 方法的请求，并设置标头、查询参数、JSON 请求体、身份验证和 {{variable}} 插值。相对 URL 会自动根据 BASE_URL 解析。

"POST to /api/users with name Jane and email [email protected] using my bearer token"

支持：GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS — Bearer / API Key / Basic 身份验证 — 自定义超时时间。

压缩模式（v0.13+）

AI Agent 会为进入其上下文窗口的每个字节付费。现在，默认情况下，request 会返回压缩后的响应，在不损失调试价值的前提下减少 70-95% 的令牌。三个可选参数可控制压缩：

模式：

• minimal — 仅返回 status、timing、size_bytes 和正文的前 200 个字符。非常适合健康检查、轮询循环或即发即忘调用。可节省约 95% 的令牌。
• normal （默认） — 过滤后的标头（剔除 Date、Server、CF-*、Set-Cookie 等）+ 截断至 max_body_bytes 的正文。适用于约 80% 的调试场景。可节省约 75% 的令牌。
• full — 完整返回未经处理的响应。需要所有标头或完整正文时使用。

对于 5 KB JSON 响应的典型节省量（≈1,500 个令牌）：

如需查看与 curl、WebFetch 及其他原生替代方案的直接对比和实测数据，请参阅下文的原生替代方案。

恢复完整响应： 每个压缩后的响应都包含一个 call_id。如果之后需要完整正文，可调用 inspect_last_response({ call_id })——无需重新执行请求。此功能适用于 request、assert 和 flow_run 的每个步骤。响应会保存在一个含 20 个槽位的环形缓冲区中，并持久化至 .api-testing/last-responses/，有效期为 1 小时。

// Example: normal (default) response
{
  "call_id": "k3m9a2xp",
  "status": 200,
  "statusText": "OK",
  "method": "GET",
  "url": "https://api.example.com/users/1",
  "timing": { "total_ms": 142 },
  "size_bytes": 5324,
  "headers": { "content-type": "application/json" },
  "body": { "id": 1, "email": "...", "...": "..." },
  "body_truncated": true,
  "hint": "Body truncated to 2048 bytes (full size: 5324B). Call inspect_last_response({ call_id: \"k3m9a2xp\" }) for the full body.",
  "tokens_saved_estimate": 820
}

原生替代方案：实际令牌开销

对比此 MCP 与 api-testing 不可用时 Claude Code 可使用的原生选项（Bash + curl、WebFetch 等）。

简而言之： 与原始 curl 相比，request 可根据模式节省 65% 到 97% 的上下文令牌，同时不损失调试信息。以下数据来自对 GET /api/v1/blog 的真实调用，该请求返回了 8 篇文章（约 8.7 KB 的 JSON、19 个响应标头）：

此表中的数据与上文“压缩模式”部分略有不同，是因为这些数据来自一个真实响应，而上表展示的是针对合成的 5 KB 响应得出的典型节省量。两者的趋势和数量级相同。

说明：

• 默认模式（normal）无需任何配置即可节省 65%：它会过滤掉嘈杂的标头（Date、Server、CF-*、Set-Cookie……），并将正文限制为 2048 字节。
• only_fields 支持包含数组索引和通配符的点号路径（items[*].name）——仅返回你指定的字段。
• MCP 还提供了没有直接原生替代方案的功能：{{variable}} 插值、已存储的环境、认证架构、工作流、Postman 导入/导出，以及 inspect_last_response，可在不重新请求服务的情况下恢复完整正文。
• 每个已注册的 MCP 在每个会话中都会增加约 300-600 个令牌的固定开销（其指令块 + 工具名称）。典型的收支平衡点：每个会话进行 1-2 次实际调用。

断言

使用结构化的通过/失败结果验证响应：

"Verify that GET /api/health returns 200, body.status is ok, and responds in under 500ms"

PASS — 3/3 assertions passed
  status === 200
  body.status === "ok"
  timing.total_ms < 500

10 个运算符：eq、neq、gt、gte、lt、lte、contains、not_contains、exists、type

请求流

在各步骤之间提取变量，以链式方式发送请求。非常适合身份验证流程和 CRUD 序列。

"Login as [email protected], extract the access token, then use it to fetch all users"

flow_run({
  steps: [
    {
      name: "login",
      method: "POST",
      url: "/auth/login",
      body: { email: "[email protected]", password: "SecurePass#99" },
      extract: { "TOKEN": "body.access_token" }
    },
    {
      name: "get-users",
      method: "GET",
      url: "/api/users",
      headers: { "Authorization": "Bearer {{TOKEN}}" }
    }
  ]
})

OpenAPI 导入

从 URL 或本地文件（JSON 和 YAML）导入规范。导入后，AI 就能了解每个端点、参数和架构。

"Import my API spec from http://localhost:3000/api-docs-json"
"Import the spec from ./openapi.yaml"
"What parameters does POST /users expect?"

支持 OpenAPI 3.x，并可完整解析 $ref、allOf、oneOf、anyOf。部分支持 OpenAPI 2.0。

模拟数据生成

根据 OpenAPI 架构生成逼真的虚假数据。支持类型、格式（email、uuid、date-time）、枚举和必填字段。

"Generate mock data for creating a user"

{
  "email": "[email protected]",
  "name": "Test User 73",
  "password": "TestPass123!",
  "role": "admin"
}

负载测试

发送 N 个并发请求并获取性能指标：

"How fast is the health endpoint with 50 concurrent requests?"

LOAD TEST — GET /api/health
Requests:    50 concurrent
Successful:  50 | Failed: 0
Req/sec:     23.31

  Min: 45ms | Avg: 187ms
  p50: 156ms | p95: 412ms | p99: 523ms
  Max: 567ms

响应差异比较

执行两个请求，并逐字段比较响应。检测回归问题或比较不同环境。

"Compare the users endpoint between dev and prod"

批量测试

运行集合中的所有已保存请求（或按标签筛选），并获取摘要：

"Run all my saved smoke tests"

BULK TEST — 8/8 passed | 1.2s total
  health       — GET  /health      → 200 (45ms)
  list-users   — GET  /users       → 200 (123ms)
  create-post  — POST /blog        → 201 (89ms)
  login        — POST /auth/login  → 200 (156ms)

集合

保存请求以便重复使用，并为其添加标签。构建回归测试套件。

"Save this request as create-user with tags auth, smoke"
"List all requests tagged smoke"

环境

环境用于保存变量（例如 BASE_URL、令牌和 API 密钥），并按上下文将它们分开。系统包含三个核心概念：

组。 组用于组织环境，并将它们关联到目录。一个组包含 N 个作用域（目录），这些目录共享该组的环境，并且恰好有一个默认环境。在组内创建环境时，该环境会归属于该组。当你 cd 进入组的某个作用域目录时，该组的环境会自动变为可用。

默认环境。 进入组的某个作用域时，默认环境会自动激活。它会在会话之间保留——重启编辑器、重新打开终端后，默认环境仍然可用。设置一次即可，无需再操心。

活动环境。 活动环境是当前用于解析变量的环境。进入作用域时，它默认设为默认环境，但你可以随时切换。活动环境的选择仅在当前会话内有效——重启后会重置为默认环境。

全局环境（未关联任何组）仍然可用。必须使用 env_switch 显式激活，并且不会在会话之间保留。

实际示例：

"Create a group called my-api"
"Add this directory as scope to my-api"
"Create a dev environment with BASE_URL http://localhost:3000"   <- auto-joins group, auto-default
"Create a prod environment with BASE_URL https://api.example.com"
"List environments"                                              <- shows dev (active, default) and prod
"Switch to prod"                                                 <- session only
"Set prod as default"                                            <- persists

自动插值。 在 URL、标头、查询参数或请求正文中的任何 {{variable}}，都会在发送请求前根据活动环境进行解析。只需设置一次 BASE_URL，所有相对路径就都能正常使用。

你的凭据绝不会离开你的计算机。 环境文件以纯 JSON 格式存储在 ~/.api-testing/ 中。不会同步到任何云端，不会嵌入导出内容，也不会纳入 git 跟踪。令牌和机密信息会留在它们应在的位置：你的磁盘上，由你掌控。

Postman 导入与导出

双向支持 Postman。可在 Postman 与你的 AI 工作流之间无缝迁移。

"Import my Postman collection from ./exported.postman_collection.json"
"Export my collection to Postman"
"Export the dev environment for Postman"

原生导出与导入

将集合和环境导出到可移植的 .atm/ 文件夹。与团队共享，或在项目之间复制。

"Export my collection and dev environment"

your-project/
└── .atm/
    ├── collection.json
    └── dev.env.json

**注意：**首次导出时，.atm/ 会自动添加到 .gitignore。

cURL 导出

将任意已保存的请求转换为可直接粘贴的 cURL 命令，并解析变量。

"Export the create-user request as curl"

curl -X POST \
  'https://api.example.com/users' \
  -H 'Authorization: Bearer eyJhbGci...' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Jane","email":"[email protected]"}'

工具参考

10 个类别中的 42 个工具：

**提示：**你无需直接调用工具。描述你的需求，AI 会选择合适的工具。

存储

所有数据都保存在本地。没有数据库、云同步或遥测功能。所有数据都以纯 JSON 文件的形式存储在 ~/.api-testing/ 中，你可以随时读取、备份或删除。

~/.api-testing/
├── groups/               # Environment groups with scopes and defaults
├── environments/         # Environment variables — tokens, keys, passwords
├── collections/          # Saved requests (shareable, no secrets)
├── specs/                # Imported OpenAPI specs
└── project-envs.json     # Session-only active environments (cleared on restart)

全局存储与项目导出。 ~/.api-testing/ 目录是你的私有全局存储，凭据保存在这里，绝不会离开此目录。导出集合或环境时，文件会保存到项目根目录下的 .atm/。首次导出时，该目录会自动添加到 .gitignore；即使你选择将其提交，凭据仍保存在 ~/.api-testing/ 中，不会复制到 .atm/。你可以放心与团队共享 .atm/ 导出文件，不必担心泄露密钥。

覆盖默认存储路径：

{
  "env": { "API_TESTING_DIR": "/path/to/custom/.api-testing" }
}

**警告：**如果将 API_TESTING_DIR 覆盖为 Git 仓库内的路径，请将 .api-testing/ 添加到 .gitignore，以免推送凭据。

架构

src/
├── index.ts              # Entry point (shebang + StdioServerTransport)
├── server.ts             # createServer() factory
├── tools/                # 42 tool handlers (one file per category)
│   ├── request.ts        # HTTP request (1)
│   ├── inspect.ts        # inspect_last_response (1)
│   ├── assert.ts         # Assertions (1)
│   ├── flow.ts           # Request chaining (1)
│   ├── collection.ts     # Collection CRUD (4)
│   ├── environment.ts    # Environments + groups (17)
│   ├── api-spec.ts       # OpenAPI import/browse (4)
│   ├── mock.ts           # Mock data generation (1)
│   ├── load-test.ts      # Load testing (1)
│   └── utilities.ts      # curl, diff, bulk, import/export (11)
├── lib/                  # Business logic (no MCP dependency)
│   ├── http-client.ts    # fetch wrapper with timing
│   ├── storage.ts        # JSON file storage engine (atomic writes)
│   ├── compress.ts       # Response compression + verbosity modes
│   ├── response-cache.ts # Ring buffer + disk cache for inspect
│   ├── schemas.ts        # Shared Zod schemas (HttpMethodSchema, AuthSchema)
│   ├── url.ts            # BASE_URL resolution
│   ├── path.ts           # Dot-notation accessor (body.data.0.id)
│   ├── interpolation.ts  # {{variable}} resolver
│   └── openapi-parser.ts # $ref + allOf/oneOf/anyOf resolution
└── __tests__/            # 10+ test suites, 171 tests

**技术栈：**TypeScript（严格模式）· MCP SDK · Zod · Vitest · tsup

MIT · 由 cocaxcode 构建