Blobfish MCP

任意 OpenAPI 规范。零配置。Claude 即用。

Blobfish 是一个 MCP 服务器，能将任何 REST API 变成 Claude 可调用的工具 —— 实时、在运行时即可完成，无需手动编写适配器。

只需给它一个 OpenAPI/Swagger URL 或 Postman 集合。Blobfish 会解析每个端点，并生成名称、描述和输入模式都齐全的类型化 MCP 工具。Claude 可以立即发现、理解并调用任何端点 —— 支持身份验证、参数化和实时调用。

演示

"我把一个域名指向它。它自己找到了规范，加载了 20 个工具，Claude 在 10 秒内就开始查询实时 API 了。"

Related MCP server: MCP OpenAPI Connector

1.3.0 新特性

OAuth 2.0 client_credentials —— 需要 OAuth 的 API（Salesforce、HubSpot OAuth 应用、Auth0 保护的 API、大多数企业网关）现在无需令牌管理即可工作。为 Blobfish 提供 token_url、client_id 和 client_secret，它就会获取 Bearer token、缓存它、在过期前刷新它，并在收到 401 时重试一次 —— 这一切对 Claude 不可见。

{ "type": "oauth2", "token_url": "https://login.example.com/oauth/token", "client_id": "${MY_CLIENT_ID}", "client_secret": "${MY_CLIENT_SECRET}" }

环境配置文件 —— 运行 npx blobfish-mcp --profile staging（或设置 BLOBFISH_PROFILE=staging），即可在存在 blobfish.staging.json 时加载该文件，并在每个 API 条目上选择 auth_profiles.staging 凭据。同样的 API，不同的密钥，一个标志搞定。

自动加载 .env —— 如果 registry API 的密钥存在于你的 .env 文件中，启动时会自动加载。无需 blobfish.json，无需调用 load_api。

STRIPE_SECRET_KEY=sk-live-...   →  Stripe tools appear in Claude on startup
GITHUB_TOKEN=ghp_...            →  GitHub tools appear in Claude on startup
OPENAI_API_KEY=sk-...           →  OpenAI tools appear in Claude on startup

这对全部 21 个预构建的 registry 条目都有效。设置 BLOBFISH_AUTO_LOAD=false 即可禁用。

工具注解 —— 每个生成的工具现在都会根据其 HTTP 方法声明 readOnlyHint、destructiveHint 和 idempotentHint（GET = 只读，DELETE = 破坏性，等等）。兼容 Claude 的客户端会使用这些提示来决定是否在调用前进行确认。

工作流条件运算符 —— 除了 == 和 != 之外，run_if 现在还支持 >、<、>=、<=。

安装

# Run directly without installing
npx blobfish-mcp https://petstore.swagger.io/v2/swagger.json

# Configure Claude Desktop (no clone needed)
npx blobfish-mcp --setup

# Or install globally
npm install -g blobfish-mcp
blobfish https://petstore.swagger.io/v2/swagger.json

需要 Node.js 18+。

连接 Claude Desktop

最快的方式 —— 无需克隆仓库：

npx blobfish-mcp --setup

或者，如果你已经克隆了仓库：

npm install
npm run setup   # auto-detects config path and writes the entry

然后在 Claude Desktop 中重新加载 MCP 配置：帮助 → 重新加载 MCP 配置。

手动设置

添加到你的 Claude Desktop 配置中（Windows 上为 %APPDATA%\Claude\claude_desktop_config.json，Mac 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "blobfish": {
      "command": "node",
      "args": ["/path/to/blobfish-mcp/server.js"],
      "env": {
        "API_KEY": "your-bearer-token-if-needed"
      }
    }
  }
}

兼容的客户端

适用于任何兼容 MCP 的客户端：

• Claude Desktop —— 主要目标，通过 npx blobfish-mcp --setup 配置

• Cursor —— 使用相同的配置格式添加到 .cursor/mcp.json

• Windsurf —— 添加到 ~/.codeium/windsurf/mcp_config.json

• Continue.dev —— 添加到 .continue/config.json 的 mcpServers 下

• Cline / Roo Cline —— 通过 Cline 的 MCP 设置面板添加

• Zed —— 添加到 Zed 的 MCP 设置中

• Smithery —— 通过 smithery.yaml 一键安装

对于使用 HTTP/SSE 而非 stdio 的客户端，请使用以下方式启动：

blobfish --http   # Streamable HTTP on http://localhost:3000/mcp
blobfish --sse    # SSE on http://localhost:3000/sse
BLOBFISH_PORT=8080 blobfish --http   # custom port

工作原理

Blobfish 以 17 个元工具 为起点，Claude 可以随时调用：

当 Claude 调用 load_api 或 discover_api 时，Blobfish 会解析规范并发送 tools/list_changed 通知 —— 新工具会立即出现。

工作流

将多个 API 调用串联为单个操作。使用 {{ steps.id.field }} 模板语法引用前面步骤的结果。

行内运行：

run_workflow(steps: [
  { id: "user",  tool: "jph_get_users_id",       args: { id: "1" } },
  { id: "posts", tool: "jph_get_posts",           args: { userId: "{{ steps.user.data.id }}" } },
  { id: "first_comments", tool: "jph_get_posts_id_comments",
    run_if: "{{ steps.posts.data.length }} != 0",
    args:   { id: "{{ steps.posts.data.0.id }}" } }
])

保存并重新运行：

save_workflow(name: "user-posts", steps: [...])
run_workflow(name: "user-posts", input: { userId: "42" })
list_workflows()

从 blobfish.json 预加载：

{
  "workflows": {
    "crypto-report": {
      "description": "BTC/ETH prices + trending coins",
      "steps": [
        { "id": "price",    "tool": "coingecko_get_simple_price",    "args": { "ids": "{{ input.coins }}", "vs_currencies": "usd" } },
        { "id": "trending", "tool": "coingecko_get_search_trending", "args": {} }
      ]
    }
  }
}

每个步骤可选项：foreach（遍历数组）、run_if（条件跳过）、on_error: "continue"（失败时不中止）。

现成示例位于 workflows/ 目录中。

blobfish.json 配置

预先配置要在启动时加载的 API。在项目根目录创建 blobfish.json：

{
  "timeout": 30000,
  "retries": 3,
  "apis": [
    {
      "url": "https://petstore.swagger.io/v2/swagger.json",
      "name": "petstore"
    },
    {
      "url": "https://api.example.com/openapi.json",
      "name": "myapi",
      "auth": {
        "type": "bearer",
        "key": "${MY_API_TOKEN}"
      },
      "timeout": 10000
    },
    {
      "url": "./local-spec.json",
      "name": "localapi",
      "mock": true
    }
  ]
}

类似 "${MY_API_TOKEN}" 这样的值会在启动时从环境变量中插值替换。

Registry

blobfish-mcp 自带 21 个预构建的 registry 条目 —— 无需规范 URL 或认证配置。

使用自动 .env 加载（1.2.0 默认）： 将 API 密钥放入 .env，工具就会自动出现。

不使用自动 .env 加载： 让 Claude 按名称加载：

load_api(spec_url: "stripe")
load_api(spec_url: "github")

或者使用 list_registry 浏览。

身份验证

在 blobfish.json 中或通过 load_api 按 API 认证

{ "type": "bearer", "key": "sk-..." }

{ "type": "apikey", "key": "abc123", "header": "X-Api-Key" }

{ "type": "basic", "username": "user", "password": "pass" }

{ "type": "oauth2", "token_url": "https://login.example.com/oauth/token", "client_id": "...", "client_secret": "...", "scope": "read write" }

OAuth 2.0 (client_credentials)

对于 oauth2，Blobfish 会在 token_url 处用客户端凭据换取 Bearer token，将其缓存在内存中，在过期前 60 秒刷新，并在 API 返回 401 时使用新 token 重试一次。可选字段：

• scope —— 以空格分隔的作用域列表

• audience —— 某些提供商（如 Auth0）必需

• client_auth —— "body"（默认，凭据放在请求体中）或 "basic"（HTTP Basic 标头），以你的提供商所期望的为准

Token 永远不会写入磁盘，也永远不会被记录。

环境配置文件

在任何 API 条目上使用 auth_profiles，将 staging 和 production 的密钥放在一起：

{
  "url": "https://api.example.com/openapi.json",
  "name": "myapi",
  "auth": { "type": "bearer", "key": "${PROD_API_TOKEN}" },
  "auth_profiles": {
    "staging": { "type": "bearer", "key": "${STAGING_API_TOKEN}" }
  }
}

然后使用 --profile staging（或 BLOBFISH_PROFILE=staging）运行。如果 blobfish.staging.json 文件存在，则会加载该文件而不是 blobfish.json。如果没有指定 profile，则原样使用 auth。

全局回退

在环境变量或 .env 文件中设置 API_KEY，即可为所有 API 启用 Bearer token 认证。

分页

使用 fetch_all 自动获取分页端点的所有页：

fetch_all(tool_name: "petstore_get_pets", args: { status: "available" }, max_pages: 5)

Blobfish 会自动检测并跟踪：

• Link: <url>; rel="next" 标头（GitHub、Stripe 风格）

• { next_cursor, cursor, after, next_page_token } 字段

• { has_more: true } + offset/limit

• { total, offset, limit } 模式

环境变量

Mock 模式

以 Mock 模式加载 API，无需发起真实的 HTTP 调用即可获得示例响应 —— 适用于没有 API 密钥时进行测试或演示：

load_api(spec_url: "https://...", mock: true)

响应由 OpenAPI 规范中的 example 字段生成。

支持的格式

• OpenAPI 3.x (JSON + YAML)

• Swagger 2.0 (JSON + YAML)

• Postman Collections v2.1

• 本地文件（./path/to/spec.json）

故障排查

Blobfish 未出现在 Claude Desktop 中

• 确保你彻底退出 Claude Desktop（托盘图标 → Quit），而不仅仅是关闭窗口

• 在 Windows Store 安装中，配置文件位于 %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json — 运行 npm run setup 可自动找到正确的路径

• 检查 node 是否在 PATH 中：打开终端并运行 node --version。如果失败，请在配置的 command 字段中使用完整路径（C:/Program Files/nodejs/node.exe）

加载规范时出现 SSRF blocked 错误

• 规范 URL 解析到了私有/内部 IP，这是出于安全考虑的有意设计。

• 如果你在开发过程中加载本地规范，请在 .env 中设置 BLOBFISH_ALLOW_LOCAL=true

Spec generates N tools (max 500) 错误

• 使用 include_tags 进行过滤：load_api(spec_url: "...", include_tags: ["repos", "issues"])

• 先运行 api_summary，看看有哪些 tags 可用

工具已出现，但调用返回错误

• 在调用失败后，执行 get_last_request_log — Claude 可以看到实际发送的 URL 和请求体，并进行自我纠正

• 检查 rate_limit_status — 你可能正在等待速率限制重置

由以下项目构建

• MCP SDK — @modelcontextprotocol/sdk

• swagger-parser — @apidevtools/swagger-parser

• Node.js 18+ 原生 fetch

• Node.js 20.6+ 原生 .env 加载（--env-file）