anyapi-mcp-server

只要有 API，就能 MCP 化。

传统的 MCP 服务器通常只挑选少数几个端点，然后就草草了事——这会将你锁定在别人认为“足够”的子集内。既然可以拥有全部 API，为什么要满足于一小部分呢？

anyapi-mcp-server 是一个通用的 MCP 服务器，它将任何 REST API 连接到 Claude、Cursor 和其他基于 LLM 的工具——只需指向 OpenAPI 规范或 Postman 集合即可。API 提供的每个端点都可以立即使用，并支持 GraphQL 风格的字段选择和自动模式推断。无需自定义服务器代码，也没有人为限制。

快速开始

1. 安装

npm install -g anyapi-mcp-server

2. 添加到你的 MCP 客户端（Cursor、Claude Desktop 等）

{
  "mcpServers": {
    "your-api": {
      "command": "npx",
      "args": [
        "-y",
        "anyapi-mcp-server",
        "--name", "your-api",
        "--spec", "path/to/openapi.json",
        "--base-url", "https://api.example.com",
        "--header", "Authorization: Bearer ${API_KEY}"
      ],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

3. 使用工具 — 使用 list_api 发现端点，使用 call_api 检查模式，使用 query_api 获取数据。

提供商示例

针对流行 API 的即用型配置：

这些适用于任何具有 OpenAPI 或 Postman 规范的 API — 上述仅为示例。Stripe、Twilio、Shopify、HubSpot 以及任何其他具有 REST API 的服务都以同样的方式工作。

CLI 参考

必需标志

可选标志

OAuth 标志

适用于使用 OAuth 2.0 而非静态令牌的 API。如果提供了三个必需标志中的任何一个，则三个都必须提供。所有标志均支持 ${ENV_VAR}。

请参阅 Google Workspace 指南以获取完整的 OAuth 示例。

工具

服务器公开了四个工具（配置 OAuth 时还会增加 auth）：

list_api — 浏览端点

发现 API 提供的功能。不带参数调用以查看所有类别，提供 category 以列出标签中的端点，或使用 search 按关键字查找端点。

call_api — 检查端点

发起真实的 HTTP 请求并返回推断出的 GraphQL 模式 (SDL) — 而不是数据本身。使用此工具发现响应结构并获取可以复制到 query_api 中的 suggestedQueries。它还会返回每个字段的令牌成本 (fieldTokenCosts) 和用于缓存重用的 dataKey。对于 PUT/PATCH 请求，会自动创建预写入备份（返回 backupDataKey）。支持用于大负载的 bodyFile，并会阻止检测到占位符值的请求。

query_api — 获取数据

获取数据并仅返回你通过 GraphQL 查询选择的字段。支持读取和写入（POST/PUT/DELETE/PATCH 的变更）。传递来自 call_api 的 dataKey 以重用缓存数据，无需进行 HTTP 调用。

# Read
{ items { id name status } _count }

# Write
mutation { post_endpoint(input: { name: "example" }) { id } }

关键参数：

• maxTokens — 响应的令牌预算。数组会被截断以适应预算。如果没有此参数或未设置 unlimited，超过约 10k 令牌的响应将被拒绝。

• unlimited — 设置为 true 以返回完整响应，不强制执行令牌预算。

• dataKey — 重用来自先前 call_api 或 query_api 响应的缓存数据。

• jsonFilter — 在 GraphQL 查询后提取嵌套值的点路径（例如 "data[].attributes.name"）。

• bodyFile — 用作请求主体的 JSON 文件的绝对路径（与 body 互斥）。用于无法内联发送的大型负载。

• skipBackup — 跳过 PUT/PATCH 请求的自动预写入备份（默认：false）。

explain_api — 阅读文档

返回端点的规范文档（参数、请求主体模式、响应代码），而不发起 HTTP 请求。

auth — OAuth 认证

仅在配置了 --oauth-* 标志时可用。管理 OAuth 流程：

• action: "start" — 返回授权 URL（或为 client_credentials 交换凭据）

• action: "exchange" — 完成授权码流程（回调会自动捕获）

• action: "status" — 显示当前令牌状态

令牌会被持久化并自动刷新。

典型工作流程

list_api          → discover what's available
     ↓
explain_api       → read the docs for an endpoint
     ↓
call_api          → inspect the response schema (returns dataKey)
     ↓
query_api         → fetch exactly the fields you need (pass dataKey for zero HTTP calls)
     ↓
query_api         → re-query with different fields using the same dataKey

工作原理

OpenAPI/Postman spec
        │
        ▼
   ┌─────────┐  ┌─────────────┐  ┌──────────┐  ┌───────────┐
   │list_api │  │ explain_api │  │ call_api │  │ query_api │
   │(browse) │  │   (docs)    │  │ (schema) │  │  (data)   │
   └─────────┘  └─────────────┘  └──────────┘  └───────────┘
        │          │ no HTTP          │               │
        ▼          ▼ request          ▼               ▼
   Spec index   Spec index     REST API call    dataKey cache
   (tags,       (params,       (with retry)     hit → no HTTP
    paths)       responses,         │            miss → fetch
                 body schema)       ▼               │
                               Infer schema +       ▼
                               return dataKey   Execute GraphQL
                                                + token budget
                                                  truncation

功能特性

• 任何 REST API — 提供 OpenAPI (JSON/YAML) 或 Postman Collection v2.x 规范作为文件或 URL

• 远程规范缓存 — HTTPS 规范会被获取一次并缓存到 ~/.cache/anyapi-mcp/

• GraphQL 字段选择 — 仅查询响应中你需要的字段

• 模式推断 — 从实时 API 响应中自动构建 GraphQL 模式

• 多样本合并 — 对最多 10 个数组元素进行采样以获得更丰富的模式

• 变更支持 — 写入操作从 OpenAPI 主体模式中获取类型化的 GraphQL 变更

• 智能建议 — call_api 根据推断出的模式返回即用型查询

• 响应缓存 — 基于文件系统的缓存，TTL 为 5 分钟；dataKey 令牌允许 query_api 在零 HTTP 调用下重用数据

• 令牌预算 — query_api 默认强制执行约 10k 令牌的安全限制；使用 maxTokens 截断最深最大的数组以适应限制，或使用 unlimited: true 获取完整响应

• 字段级令牌成本 — call_api 返回 fieldTokenCosts 树，以便 LLM 可以做出明智的字段选择

• 速率限制跟踪 — 解析 X-RateLimit-* 标头，并在限制即将耗尽时发出警告

• 分页检测 — 自动检测响应中的游标、下一页令牌和基于链接的分页模式

• JSON 过滤器 — query_api 接受用于查询后提取的 jsonFilter 点路径（例如 "data[].name"）

• 带退避的重试 — 针对 429/5xx 错误自动重试，支持指数退避和 Retry-After

• 多格式支持 — 解析 JSON、XML、CSV 和纯文本响应

• 安全写入 — PUT/PATCH 请求在写入前自动对资源进行快照 (backupDataKey)；在发送前检测并阻止占位符值（例如 PLACEHOLDER, TODO, file://）

• 基于文件的请求主体 — bodyFile 参数接受 JSON 文件的绝对路径，支持无法内联发送的大型负载

• 丰富的错误信息 — 结构化的错误消息，包含特定于状态的建议和用于自我修正的规范上下文

• OAuth 2.0 — 支持授权码（带 PKCE）和客户端凭据流程，并自动刷新令牌

• 环境变量插值 — 在基础 URL、标头和规范路径中支持 ${ENV_VAR}

• 请求日志记录 — 可选的 NDJSON 日志，支持敏感标头屏蔽

支持的规范格式

• OpenAPI 3.x (JSON 或 YAML)

• OpenAPI 2.0 / Swagger (JSON 或 YAML)

• Postman Collection v2.x (JSON)

许可证

专有非商业用途。个人和教育用途免费。商业用途需要书面许可。详情请参阅 LICENSE。