Blobfish MCP

Любая спецификация OpenAPI. Ноль конфигурации. Готово для Claude.

Blobfish — это MCP-сервер, который превращает любой REST API в инструменты, вызываемые из Claude, — мгновенно, в рантайме, без ручного написания адаптеров.

Укажите ему URL спецификации OpenAPI/Swagger или коллекцию Postman. Blobfish разбирает каждый эндпоинт и генерирует типизированные MCP-инструменты с именами, описаниями и входными схемами. Claude может сразу обнаруживать, анализировать и вызывать любой эндпоинт — с аутентификацией, с параметрами и в реальном времени.

Демо

«Я указал ему доменное имя. Он сам нашёл спецификацию, загрузил 20 инструментов, и через 10 секунд Claude уже запрашивал живой API».

Related MCP server: mcp-openapi

Что нового в версии 1.3.0

OAuth 2.0 client_credentials — API, которым нужен OAuth (Salesforce, OAuth-приложения HubSpot, API, защищённые Auth0, большинство корпоративных шлюзов), теперь работают без какого-либо управления токенами. Передайте Blobfish token_url, client_id и client_secret; он получает bearer-токен, кэширует его, обновляет до истечения срока и при ответе 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, если он существует, и выбрать учётные данные auth_profiles.staging для каждой записи API. Те же API, другие ключи — один флаг.

Автозагрузка .env — если ключ 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 встроенной записи реестра. Установите BLOBFISH_AUTO_LOAD=false, чтобы отключить.

Аннотации инструментов — каждый сгенерированный инструмент теперь объявляет readOnlyHint, destructiveHint и idempotentHint на основе HTTP-метода (GET = только чтение, DELETE = разрушительная операция и т. д.). Клиенты, совместимые с Claude, используют эти подсказки, чтобы решить, когда запрашивать подтверждение перед вызовом.

Операторы условий в workflow — 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

Затем перезагрузите конфигурацию MCP в Claude Desktop: Help → Reload MCP Configuration.

Ручная настройка

Добавьте в конфигурацию Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json в Windows, ~/Library/Application Support/Claude/claude_desktop_config.json в macOS):

{
  "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 — добавьте через панель настроек MCP в Cline

• Zed — добавьте в настройки MCP в Zed

• 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 — новые инструменты появляются сразу.

Workflow

Объединяйте несколько API-callов в одну операцию. Ссылайтесь на результаты предыдущих шагов через синтаксис шаблонов {{ 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}" подставляются из переменных окружения при запуске.

Реестр

21 встроенная запись реестра поставляется с blobfish-mcp — не нужен ни URL спецификации, ни конфигурация аутентификации.

С автозагрузкой из .env (по умолчанию в 1.2.0): положите ключ API в .env — и инструменты появятся автоматически.

Без aut-загрузки из .env: попросите Claude загрузить по имени:

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

Или просмотрите список через list_registry.

| Имя | API | Обязательные переменные окружения | | --- | — | --- | | anthropic | Anthropic API | ANTHROPIC_API_KEY | | coingecko | CoinGecko API | (нет — публичное) | | 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 | (нет — демо) | | 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 |

Аутентификация

Аутентификация определенного в blobfish.json или через 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)

Для oauth2 Blobfish обменивает ваши учётные данные на bearer-токен через token_url, хранит его в памяти, обновляет за 60 секунд до истечения и при получении 401 сохраняет запрос один раз.

Необязательные поля:

• scope — разделённые пробелом области

• audience — необходимое для некоторых провайдеров (например, Auth0)

• client_auth — "body" (по умолчанию, передаётся в теле формы) или "basic" (заголовок HTTP Basic) — в зависимости от того, что ожидает ваш провайдер

Токены никогда не записываются на диск и не сохраняются в журнал.

Профили окружения

Поместите staging- и production-ключи рядом друг с другом через auth_profiles в любой записи API:

{
  "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 целиком. Без указанного профиля используется auth как есть.

Недокументированный глобальный fallback

Установите API_KEY в вашем окружении или файле .env для аутентификации все по Bearer-токену.

Пагинация

Используйте fetch_all для автоматического получения всех страниц с эндпоинта, поддержи период:

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

Blobfish автоматически находит и обрабатывает:

• заголовки Link: <url>; rel="next" (стиль GitHub, Stripe)

• поля { next_cursor, offes, after, next_page_token }

• { has_more: true } + offset/limit

• шаблоны { total, offset, limit }

Переменные окружения

Mock-режим

Загрузите API в mock-режиме, чтобы получать примеры ответов без реальных HTTP-запросов — удобно для тестирования и демо-режима без API-ключей:

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

Ответы генерируются из полей example в OpenAPI-спецификации.

Поддерживаемые форматы

• 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. Если команда не работает, используйте полный путь (C:/Program Files/nodejs/node.exe) в поле command конфигурации.

Ошибка SSRF blocked при загрузке спецификации

• URL спецификации резолвится в частный/внутренний IP-адрес. Это сделано намеренно в целях безопасности.

• Если во время разработки вы загружаете локальную спецификацию, укажите BLOBFISFISH_ALLOW_LOOCAL=true в файле .env.

**Ошибка Spec генерируется N tools (max 500)

• Исп**ользуйте include_tags для фильтрации: load_api(spec_url: "...", include_tags: ["repos", "issues"]).

• Сначачала запустите api_summary, чтобы посмотреть доступные теги.

Инструменты отображаются, но вызовы возвращают последние

• Вызовите get_last_request_log после неудачного вызова — Claude сможет увидетьточный URL и отправельное тело запроса и само-ит исправить.

• Провертите rate_limit_status — возможно, вы ожидаете сброса огронны.

Создано с помощью

• MCP SDK — @modelcontextprotocol/sdk

• swagger-parser — @apidvools/swagger-parser

• Node.js 18+ встроенний fetch

• Node.js 20.6+ встроенная загурзка .env (--env-file)