@blossai/mcp-server

Model Context Protocol server for Blossom. Exposes the Blossom Public API to LLM clients (Claude Desktop, Cursor, Continue, etc.) so an AI agent can browse the viral-content library, surface trends, generate ideas, and trigger fresh analyses.

Install

The recommended path is npx — no global install required.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "blossom": {
      "command": "npx",
      "args": ["-y", "@blossai/mcp-server"],
      "env": {
        "BLOSSOM_API_KEY": "blsm_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The Blossom tools appear in the tool list.

Cursor / Continue / other MCP clients

Use the same JSON shape in your client's MCP config. Most clients accept a command + args + env triple.

Getting an API key

1. Sign in to Blossom and open Account → API Keys.
2. Make sure you're on an active Pro, Premium, or Platin plan.
3. Click Create key, copy the blsm_... value shown once, paste it into BLOSSOM_API_KEY above.

The Free tier cannot create keys.

Configuration

| Env var | Default | Purpose | |---|---|---| | BLOSSOM_API_KEY | (required) | API key from Account → API Keys | | BLOSSOM_API_URL | https://api.blossai.com | Override for self-hosted / staging |

Tools

Read-only data:

| Tool | Returns | |---|---| | list_videos / get_video | Analyzed videos with metrics, classifications, tactics | | list_influencers / get_influencer | Creator profiles | | list_formats / get_format | Viral format classes with aggregate metrics | | list_hooks / get_hook | Hook patterns (first 1-3 seconds) | | list_tactics / get_tactic | Specific techniques (pattern interrupts, open loops, ...) | | list_music / get_track | Trending audio with BPM / key / energy | | list_suggestions / get_suggestion | AI-generated content ideas | | list_trending | What's breaking right now | | list_categories | Categories the key can read |

Analysis:

| Tool | Purpose | |---|---| | trigger_analysis | Submit a TikTok/Instagram URL → returns analysis_id immediately | | get_analysis_status | Poll the analysis (recommended cadence: 5s; finishes in ~20-45s) |

Account:

| Tool | Purpose | |---|---| | get_account_info | Plan, rate limit, usage, remaining quota |

Rate limits

Per Blossom Public API:

| Plan | Rate limit | |---|---| | Pro | 30 req/min | | Premium | 60 req/min | | Platin | 100 req/min |

The MCP server surfaces 429 / 403 responses as MCP error tool-results so the LLM can react gracefully.

Local development

npm install
BLOSSOM_API_KEY=blsm_... npm run dev    # tsx-based hot reload
npm run build && npm run inspect         # MCP Inspector UI

License

MIT