Blobfish MCP

Any OpenAPI spec. Zero config. Claude-ready.

Blobfish is an MCP server that turns any REST API into Claude-callable tools — instantly, at runtime, with no manual adapter writing.

Point it at an OpenAPI/Swagger URL or a Postman collection. Blobfish parses every endpoint and generates typed MCP tools with names, descriptions, and input schemas. Claude can immediately discover, reason about, and call any endpoint — authenticated, parameterized, and live.

---

Demo

"I pointed it at a domain name. It found the spec itself, loaded 20 tools, and Claude was querying a live API in 10 seconds."

---

What's new in 1.3.0

OAuth 2.0 client_credentials — APIs that need OAuth (Salesforce, HubSpot OAuth apps, Auth0-protected APIs, most enterprise gateways) now work with zero token management. Give Blobfish a token_url, client_id, and client_secret; it fetches the bearer token, caches it, refreshes it before expiry, and retries once on 401 — all invisible to Claude.

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

Environment profiles — run npx blobfish-mcp --profile staging (or set BLOBFISH_PROFILE=staging) to load blobfish.staging.json if it exists, and to select auth_profiles.staging credentials on each API entry. Same APIs, different keys, one flag.

<details> <summary>What was new in 1.2.0</summary>

Auto-.env loading — if a registry API's key is in your .env, it loads automatically at startup. No blobfish.json, no load_api call.

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

This works for all 21 pre-built registry entries. Set BLOBFISH_AUTO_LOAD=false to disable.

Tool annotations — every generated tool now declares readOnlyHint, destructiveHint, and idempotentHint based on its HTTP method (GET = read-only, DELETE = destructive, etc.). Claude-compatible clients use these hints to decide when to confirm before calling.

Workflow condition operators — run_if now supports >, <, >=, <= in addition to == and !=.

</details>

---

Install

# 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

Requires Node.js 18+.

---

Connect to Claude Desktop

The fastest way — no clone required:

npx blobfish-mcp --setup

Or if you've cloned the repo:

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

Then reload MCP config in Claude Desktop: Help → Reload MCP Configuration.

Manual setup

Add to your Claude Desktop config (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

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

---

Compatible clients

Works with any MCP-compatible client:

• Claude Desktop — primary target, setup via npx blobfish-mcp --setup
• Cursor — add to .cursor/mcp.json using the same config format
• Windsurf — add to ~/.codeium/windsurf/mcp_config.json
• Continue.dev — add to .continue/config.json under mcpServers
• Cline / Roo Cline — add via Cline's MCP settings panel
• Zed — add to Zed's MCP settings
• Smithery — one-click install via smithery.yaml

For clients that use HTTP/SSE instead of stdio, start with:

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

---

How it works

Blobfish starts with 17 meta-tools Claude can always call:

Tool	Description
list_registry	List all pre-configured APIs — load any by name instantly
discover_api	Auto-find a spec from just a domain — probes 25 common paths
load_api	Load by URL, registry name, or local file. Supports include_tags, exclude_tags, shallow, mock
set_api_auth	Update credentials for a loaded API mid-conversation
fetch_all	Auto-paginate any endpoint — Link headers, cursor, offset
save_workflow	Save a workflow by name so it can be re-run with run_workflow(name: "...")
list_workflows	List all saved workflows and their step counts
run_workflow	Multi-step pipelines with {{ template }} syntax, foreach, and run_if
get_last_request_log	See the exact URL/body of the last N requests — use when debugging 400 errors
rate_limit_status	Show which APIs are rate-limited and when they reset
cache_stats	Cache hit rate, size, and entries
clear_cache	Clear cached responses
test_connection	Ping a loaded API and get status + response time
inspect_tool	Show the full input schema of any loaded tool
api_summary	Plain-English overview of a loaded API by capability group
list_apis	List all loaded APIs and tool counts
unload_api	Remove a loaded API and all its tools

When Claude calls load_api or discover_api, Blobfish parses the spec and sends a tools/list_changed notification — new tools appear immediately.

---

Workflows

Chain multiple API calls into a single operation. Reference earlier step results with {{ steps.id.field }} template syntax.

Run inline:

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 and re-run:

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

Pre-load from 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": {} }
      ]
    }
  }
}

Per-step options: foreach (iterate over an array), run_if (conditional skip), on_error: "continue" (don't abort on failure).

Ready-to-use examples are in the workflows/ folder.

---

blobfish.json config

Pre-configure APIs to load at startup. Create blobfish.json in the project root:

{
  "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
    }
  ]
}

Values like "${MY_API_TOKEN}" are interpolated from environment variables at startup.

---

Registry

21 pre-built registry entries ship with blobfish-mcp — no spec URL or auth config required.

With auto-.env loading (1.2.0 default): put the API key in your .env and the tools appear automatically.

Without auto-.env: ask Claude to load by name:

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

Or browse with list_registry.

Name	API	Required env var(s)
anthropic	Anthropic API	ANTHROPIC_API_KEY
coingecko	CoinGecko API	(none — public)
datadog	Datadog API	DATADOG_API_KEY
discord	Discord API	DISCORD_BOT_TOKEN
github	GitHub REST API	GITHUB_TOKEN
hubspot	HubSpot CRM API	HUBSPOT_ACCESS_TOKEN
jira	Jira Cloud API	JIRA_EMAIL, JIRA_API_TOKEN
linear	Linear API	LINEAR_API_KEY
notion	Notion API	NOTION_TOKEN
openai	OpenAI API	OPENAI_API_KEY
openmeteo	Open-Meteo Weather API	(none — public)
openweathermap	OpenWeatherMap API	OPENWEATHERMAP_API_KEY
pagerduty	PagerDuty API	PAGERDUTY_API_KEY
petstore	Swagger Petstore	(none — demo)
resend	Resend API	RESEND_API_KEY
shopify	Shopify Admin API	SHOPIFY_ACCESS_TOKEN
slack	Slack Web API	SLACK_BOT_TOKEN
spotify	Spotify Web API	SPOTIFY_ACCESS_TOKEN
stripe	Stripe API	STRIPE_SECRET_KEY
twilio	Twilio API	TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN
vercel	Vercel API	VERCEL_TOKEN

---

Authentication

Per-API auth in blobfish.json or via load_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)

For oauth2, Blobfish exchanges your client credentials for a bearer token at token_url, caches it in memory, refreshes it 60 seconds before expiry, and retries once with a fresh token if the API returns 401. Optional fields:

• scope — space-separated scopes
• audience — required by some providers (e.g. Auth0)
• client_auth — "body" (default, credentials in the form body) or "basic" (HTTP Basic header), matching whichever your provider expects

Tokens never touch disk and are never logged.

Environment profiles

Keep staging and production keys side by side with auth_profiles on any API entry:

{
  "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}" }
  }
}

Then run with --profile staging (or BLOBFISH_PROFILE=staging). If a blobfish.staging.json file exists, it is loaded instead of blobfish.json entirely. Without a profile, auth is used as-is.

Global fallback

Set API_KEY in your environment or .env file for Bearer token auth across all APIs.

---

Pagination

Use fetch_all to automatically retrieve all pages from a paginated endpoint:

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

Blobfish automatically detects and follows:

• Link: <url>; rel="next" headers (GitHub, Stripe style)
• { next_cursor, cursor, after, next_page_token } fields
• { has_more: true } + offset/limit
• { total, offset, limit } patterns

---

Environment variables

Variable	Default	Description
API_KEY	—	Global Bearer token for all APIs
BLOBFISH_AUTO_LOAD	true	Set to false to disable auto-loading registry APIs from .env
BLOBFISH_TIMEOUT	30000	Request timeout in ms
BLOBFISH_RETRIES	3	Retry attempts on 5xx errors
BLOBFISH_CACHE_TTL	60	Response cache TTL in seconds
BLOBFISH_LOG	—	Log file path, or true for ./blobfish.log
BLOBFISH_PORT	3000	Port for --http / --sse transports
BLOBFISH_PROFILE	—	Environment profile, same as --profile (e.g. staging)
BLOBFISH_ALLOW_LOCAL	false	Set to true to allow loading local file specs (dev only)

---

Mock mode

Load an API in mock mode to get example responses without making real HTTP calls — useful for testing or demoing without API keys:

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

Responses are generated from the example fields in the OpenAPI spec.

---

Supported formats

• OpenAPI 3.x (JSON + YAML)
• Swagger 2.0 (JSON + YAML)
• Postman Collections v2.1
• Local files (./path/to/spec.json)

---

Troubleshooting

Blobfish doesn't appear in Claude Desktop

• Make sure you fully quit Claude Desktop (tray icon → Quit), not just close the window
• On Windows Store install, config goes in %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json — run npm run setup to find the right path automatically
• Check that node is in PATH: open a terminal and run node --version. If it fails, use the full path (C:/Program Files/nodejs/node.exe) in the config's command field

SSRF blocked error when loading a spec

• The spec URL resolves to a private/internal IP. This is intentional for security.
• If you're loading a local spec during development: set BLOBFISH_ALLOW_LOCAL=true in your .env

Spec generates N tools (max 500) error

• Use include_tags to filter: load_api(spec_url: "...", include_tags: ["repos", "issues"])
• Run api_summary first to see what tags are available

Tools appear but calls return errors

• Call get_last_request_log after the failed call — Claude can see the exact URL and body sent and self-correct
• Check rate_limit_status — you may be waiting for a rate limit to reset

---

Built with

• MCP SDK — @modelcontextprotocol/sdk
• swagger-parser — @apidevtools/swagger-parser
• Node.js 18+ native fetch
• Node.js 20.6+ native .env loading (--env-file)