@boomstream/mcp

MCP server (Model Context Protocol) providing Boomstream API as tools for LLM agents: Claude Desktop, claude.ai, VS Code MCP extension, and any compatible client.

Status: stdio and SSE transports are live. Per-user OAuth is on the roadmap — see the bundled CHANGELOG.md for updates.

Connection guide: See https://mcp.boomstream.com/ for the canonical connection guide (auth, endpoints, client setup, quick-start examples).

What it does

LLM agents call tools like boomstream_media_info, boomstream_ppv_list_buyers, boomstream_live_create — the server translates them to HTTP calls against https://boomstream.com/api/, parses the responses, and returns structured JSON. ~100 tools across 17 API sections: media, live, ppv, conference, folder, playlist, stats, chat, screenshot, subtitles, timecodes, webhook, project, record-live, live-ipcamera, player-api, general.

Transports:

• stdio — for Claude Desktop (local child process). Shipped.
• SSE — for claude.ai web and remote clients (hosted at mcp.boomstream.com). Available in v0.3.0.

Quick start

BOOMSTREAM_API_KEY=your-key npx -y @boomstream/mcp@latest stdio

Or install globally:

npm install -g @boomstream/mcp@latest
BOOMSTREAM_API_KEY=your-key boomstream-mcp

@latest always resolves to the newest published version. Pin a specific version (e.g., @boomstream/[email protected]) if you need reproducible installs.

Available tools

| Section | Tools | Description | Examples | |---|---:|---|---| | media | 6 | Recorded media (VOD): info, create, upload, bulk-info | boomstream_media_bulkinfo, boomstream_media_info | | live | 7 | Live broadcast streams: create, manage, schedule | boomstream_live_info, boomstream_live_list | | ppv | 13 | Pay-per-view subscriptions: create, buyers, media access | boomstream_ppv_create, boomstream_ppv_update | | conference | 10 | Video conference sessions: create, manage, participants | boomstream_conference_info, boomstream_conference_list | | media_folder | 4 | Folder hierarchy for VOD media assets | boomstream_media_folder, boomstream_media_folder_create | | live_folder | 4 | Folder hierarchy for live broadcast assets | boomstream_live_folder, boomstream_live_folder_create | | materials_folder | 4 | Folder hierarchy for materials assets | boomstream_materials_folder, boomstream_materials_folder_create | | playlist | 7 | Playlists of media items: create, update, reorder | boomstream_playlist_create, boomstream_playlist_update | | stats | 3 | Viewing statistics per project, target, or session | boomstream_stats_project, boomstream_stats_target | | chat | 5 | Chat settings and messages for broadcasts | boomstream_chat_init, boomstream_chat_info | | screenshot | 4 | Thumbnail and screenshot management for media | boomstream_screenshot_info, boomstream_screenshot_create | | subtitles | 6 | Subtitle tracks: enable, upload, set default | boomstream_subtitles_info, boomstream_subtitles_enable | | timecodes | 4 | Chapter/timecode markers for video navigation | boomstream_timecodes_info, boomstream_timecodes_enable | | webhook | 6 | Webhook endpoint management: list, create, update, delete | boomstream_webhook_list, boomstream_webhook_info | | app | 5 | Project (app) settings, users, and configuration | boomstream_app_create, boomstream_app_info | | recordLive | 9 | Record-live sessions: create and manage recordings | boomstream_recordLive_info, boomstream_recordLive_list | | cameraLive | 7 | IP camera stream integration for live broadcasts | boomstream_cameraLive_info, boomstream_cameraLive_list | | general | 1 | General API utilities (server info, capabilities) | boomstream_general_info |

The full schema is in schemas/boomstream.json. Regenerate with pnpm build-schema.

Tool catalog

Group tools by resource for quick lookup. Read = safe/idempotent; Write = state-mutating (create/update/delete); Upload = multipart POST; Actions = other operations.

Media (VOD)

• Read: boomstream_media_bulkinfo, boomstream_media_info
• Write: boomstream_media_create, boomstream_media_update, boomstream_media_delete
• Upload: boomstream_media_upload

Live broadcast

• Read: boomstream_live_info, boomstream_live_list
• Write: boomstream_live_create, boomstream_live_update, boomstream_live_delete
• Actions: boomstream_live_record, boomstream_live_restream

PPV (pay-per-view)

• Read: boomstream_ppv_list, boomstream_ppv_listmedia, boomstream_ppv_listbuyers, boomstream_ppv_contacts
• Write: boomstream_ppv_create, boomstream_ppv_update, boomstream_ppv_delete, boomstream_ppv_addmedia, boomstream_ppv_deletemedia, boomstream_ppv_addbuyer, boomstream_ppv_updatebuyer, boomstream_ppv_deletebuyer, boomstream_ppv_updatecontacts

Conference

• Read: boomstream_conference_info, boomstream_conference_list, boomstream_conference_client_list, boomstream_conference_client_info
• Write: boomstream_conference_create, boomstream_conference_update, boomstream_conference_client_update, boomstream_conference_client_delete, boomstream_conference_delete
• Actions: boomstream_conference_invite

Media folders

• Write: boomstream_media_folder_create, boomstream_media_folder_update, boomstream_media_folder_delete
• Actions: boomstream_media_folder

Live folders

• Write: boomstream_live_folder_create, boomstream_live_folder_update, boomstream_live_folder_delete
• Actions: boomstream_live_folder

Materials folders

• Write: boomstream_materials_folder_create, boomstream_materials_folder_update, boomstream_materials_folder_delete
• Actions: boomstream_materials_folder

Playlists

• Read: boomstream_playlist_list, boomstream_playlist_listmedia
• Write: boomstream_playlist_create, boomstream_playlist_update, boomstream_playlist_delete, boomstream_playlist_addmedia, boomstream_playlist_deletemedia

Statistics

• Read: boomstream_stats_project, boomstream_stats_target, boomstream_stats_session

Chat

• Read: boomstream_chat_info
• Actions: boomstream_chat_init, boomstream_chat_create_message, boomstream_chat_update_message, boomstream_chat_delete_message

Screenshots

• Read: boomstream_screenshot_info
• Write: boomstream_screenshot_create, boomstream_screenshot_update, boomstream_screenshot_delete

Subtitles

• Read: boomstream_subtitles_info, boomstream_subtitles_download
• Upload: boomstream_subtitles_upload
• Actions: boomstream_subtitles_enable, boomstream_subtitles_enabledefault, boomstream_subtitles_enableautoplay

Timecodes

• Read: boomstream_timecodes_info, boomstream_timecodes_download
• Upload: boomstream_timecodes_upload
• Actions: boomstream_timecodes_enable

Webhook

• Read: boomstream_webhook_list, boomstream_webhook_info, boomstream_webhook_events
• Write: boomstream_webhook_update, boomstream_webhook_create, boomstream_webhook_delete

Project (app)

• Read: boomstream_app_info, boomstream_app_list
• Write: boomstream_app_create, boomstream_app_update, boomstream_app_delete

Record-live

• Read: boomstream_recordLive_info, boomstream_recordLive_list
• Write: boomstream_recordLive_update, boomstream_recordLive_delete
• Actions: boomstream_recordLive_create_record_live, boomstream_recordLive_upcoming_live, boomstream_recordLive_start_upcoming_live, boomstream_recordLive_stop_upcoming_live, boomstream_recordLive_remove_upcoming_live

Live IP camera

• Read: boomstream_cameraLive_info, boomstream_cameraLive_list
• Write: boomstream_cameraLive_create, boomstream_cameraLive_update, boomstream_cameraLive_delete
• Actions: boomstream_cameraLive_record, boomstream_cameraLive_toggle

General

• Read: boomstream_general_info

Claude Desktop

Add to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "boomstream": {
      "command": "npx",
      "args": ["-y", "@boomstream/mcp", "stdio"],
      "env": {
        "BOOMSTREAM_API_KEY": "your-api-key"
      }
    }
  }
}

After saving, restart Claude Desktop.

claude.ai / SSE

Connect from claude.ai (web), VS Code MCP extension, or any SSE-capable MCP client — no local install required.

Auth: pass your Boomstream API key as a Bearer token.

claude.ai

1. Go to Settings → Integrations (or Settings → MCP Servers depending on your plan).
2. Add a new server:
   • URL: https://mcp.boomstream.com/sse
   • Authorization: Bearer <your-boomstream-api-key>
3. Claude will discover ~100 boomstream_* tools automatically.

VS Code MCP extension

// settings.json
{
  "mcp.servers": {
    "boomstream": {
      "type": "sse",
      "url": "https://mcp.boomstream.com/sse",
      "headers": {
        "Authorization": "Bearer <your-boomstream-api-key>"
      }
    }
  }
}

curl smoke test

curl -sI -H "Authorization: Bearer <apikey>" https://mcp.boomstream.com/sse | head -5
# HTTP/2 200, content-type: text/event-stream

CLI reference

boomstream-mcp [stdio]         Start MCP server (stdio transport)
boomstream-mcp --version, -v   Print version
boomstream-mcp --help, -h      Show help

boomstream-mcp with no arguments is equivalent to boomstream-mcp stdio.

To self-host the SSE server:

BOOMSTREAM_API_KEY=your-key boomstream-mcp-sse
# Listens on PORT (default 9090). Set PORT env var to override.

Requirements

• Node.js >= 20
• A Boomstream account with API access. Get your API key in your project settings.

Security

Your Boomstream API key grants full access to your tenant's ~100 tools, including irreversible operations (delete media, delete PPV plans, etc.). Keep it secret — treat it like a password. If you suspect a leak, contact your Boomstream project owner to generate a replacement key and revoke the old one.

Per-user OAuth (scoped tokens) is on the roadmap — see CHANGELOG.md for updates.

How tool schemas are generated

JSONSchema for each tool is not hand-written. The source of truth is the Boomstream API documentation database. The script scripts/build-schema.mjs parses the markdown and produces schemas/boomstream.json covering all ~100 methods in a single run. The generated file is committed to the repository and shipped in the npm package.

Development

pnpm install   # install dependencies
pnpm build     # TypeScript compile → dist/
pnpm test      # run tests (vitest)

For schema regeneration, smoke testing, and SSE self-hosting, see docs/development.md in the repository.

Troubleshooting

BOOMSTREAM_API_KEY is not set

The server exits immediately with an error about a missing API key. Set it before starting:

BOOMSTREAM_API_KEY=your-key npx -y @boomstream/mcp stdio
# or in Claude Desktop config under "env": { "BOOMSTREAM_API_KEY": "…" }

Network timeout or 5xx from boomstream.com/api/

The client retries up to 3 times with exponential backoff (100 ms → 400 ms → 1 600 ms). If all attempts fail, the tool returns an error. Check your network connectivity and boomstream.com status.

Invalid API key (401/403)

Verify your key in Boomstream project settings → API. Keys are project-scoped; make sure the key matches the project you intend to query.

Claude Desktop doesn't list any Boomstream tools

1. Check the MCP server logs:
   • macOS: ~/Library/Logs/Claude/mcp*.log
   • Windows: %APPDATA%\Claude\logs\
2. Confirm BOOMSTREAM_API_KEY is set in the env block of your claude_desktop_config.json.
3. Restart Claude Desktop after any config change.
4. Run the server manually to verify it starts without errors:

   BOOMSTREAM_API_KEY=your-key npx -y @boomstream/mcp stdio

Releases

Full release notes are in the CHANGELOG.md file bundled with the npm package. The full release timeline is available via npm view @boomstream/mcp time --json.

Roadmap

SSE transport ✅ Live in v0.3.0. mcp.boomstream.com/sse — connect from claude.ai or any SSE-capable MCP client using your API key as a Bearer token.

OAuth (per-user auth): each Boomstream account holder connects with their own credentials instead of a shared API key. In development — check CHANGELOG.md for updates.

License

MIT — see the bundled LICENSE file.