Scrumball Influencer Plugins

Give your AI agent the power to find, evaluate, and manage influencers across YouTube, Instagram, and TikTok — powered by Scrumball.

Works with Claude Code / Codex / OpenClaw / any MCP or HTTP-compatible agent.

What it does

Your AI agent becomes an influencer research assistant:

1. Search — Find creators by keyword, country, follower range, gender, language
2. Evaluate — Get full profiles with engagement rate, CPM/CPE pricing, 30-day trends, recent posts
3. Take action — Save vetted creators to Scrumball collections for outreach and campaign management

"Find TikTok beauty creators in the US, 100k–500k followers, engagement rate > 5%"

 → Agent searches, filters, compares profiles locally
 → Presents a shortlist with pricing and engagement data
 → Saves your picks to Scrumball for one-click outreach

Install

Prerequisites

Get your API key from scrumball.com (format: sk_live_xxx).

Claude Code

claude plugin install scrumball

Set your API key:

export SCRUMBALL_API_KEY=sk_live_your_key_here

Verify: run /mcp in Claude Code to confirm the scrumball server is connected.

Use /scrumball:search-creators or just describe what you need — Claude will pick the right tools automatically.

Codex

Add the MCP server to your project config (.codex/config.toml):

[mcp_servers.scrumball]
command = "npx"
args = ["-y", "scrumball-influencer-plugins", "scrumball-mcp"]
env = { SCRUMBALL_API_KEY = "sk_live_your_key_here" }

Or via CLI:

codex mcp add scrumball \
  --env SCRUMBALL_API_KEY=sk_live_your_key_here \
  -- npx -y scrumball-influencer-plugins scrumball-mcp

Agents SDK (Python):

from agents import Agent
from agents.mcp import MCPServerStdio

async with MCPServerStdio(
    name="Scrumball",
    params={
        "command": "npx",
        "args": ["-y", "scrumball-influencer-plugins", "scrumball-mcp"],
        "env": {"SCRUMBALL_API_KEY": "sk_live_your_key_here"},
    },
) as scrumball:
    agent = Agent(
        name="Influencer Researcher",
        instructions="Search and analyze influencers using Scrumball tools.",
        mcp_servers=[scrumball],
    )

OpenClaw

openclaw plugins install scrumball-influencer-plugins

For local development from this repository, link the current project instead:

openclaw plugins install -l .

Restart OpenClaw, then configure the plugin entry. The plugin id is scrumball.

{
  "plugins": {
    "allow": ["scrumball"],
    "entries": {
      "scrumball": {
        "config": {
          "SCRUMBALL_API_KEY": "sk_live_your_key_here"
        }
      }
    }
  }
}

If OpenClaw reports plugins.allow: plugin not found: scrumball, the plugin was not discovered at startup. Verify with:

openclaw plugins list
openclaw plugins doctor

You should see the installed plugin id as scrumball. If it does not appear, reinstall the package under the same user/home that runs OpenClaw.

Any MCP-compatible Agent

The package ships a standard MCP stdio server:

SCRUMBALL_API_KEY=sk_live_xxx npx -y scrumball-influencer-plugins scrumball-mcp

Point your agent's MCP config to this command. 10 tools are auto-discovered via the MCP protocol.

REST API

For HTTP-based agents or custom integrations:

SCRUMBALL_API_KEY=sk_live_xxx npx -y scrumball-influencer-plugins scrumball-server

| Method | Path | Description | |--------|------|-------------| | GET | /api/v1/health | Health check | | GET | /api/v1/tools | List all tools (for agent discovery) | | POST | /api/v1/tools/{name} | Execute a tool |

Auth: Authorization: Bearer sk_live_xxx or X-API-Key: sk_live_xxx

OpenAPI 3.1 spec included at openapi.json.

Tools

Creators — Search & Analyze

| Tool | What it does | |------|-------------| | scrumball_search_creators | Search creators with filters: platform, keyword, country, followers, gender, language | | scrumball_get_creator_detail | Full profile — engagement rate, CPM/CPE pricing, 30-day trends, publish frequency | | scrumball_batch_creator_details | Batch profiles for up to 50 creators at once | | scrumball_get_creator_posts | Recent posts with views, likes, comments, engagement data | | scrumball_batch_creator_posts | Batch posts for up to 50 creators |

Collections — Save & Take Action

| Tool | What it does | |------|-------------| | scrumball_list_collections | List your saved collections | | scrumball_create_collection | Create a new collection for a campaign | | scrumball_get_collection_creators | See creators in a collection | | scrumball_add_to_collection | Save creators to a collection (max 50 per call) | | scrumball_remove_from_collection | Remove creators from a collection |

When to use collections: Your agent analyzes creators locally — no need to save anything. Collections are for when you're ready to take action: auto-outreach, campaign management, or team collaboration on the Scrumball platform.

Platforms

Scrumball provides unified data across three platforms:

| | YouTube | Instagram | TikTok | |--|---------|-----------|--------| | Creator search | ✓ | ✓ | ✓ | | Full profile + pricing | ✓ | ✓ | ✓ | | Post analytics | ✓ | ✓ | ✓ | | Collections | ✓ | ✓ | ✓ |

Configuration

| Variable | Default | Description | |----------|---------|-------------| | SCRUMBALL_API_KEY | — | Required. Your Scrumball API key | | SCRUMBALL_API_URL | https://api.scrumball.com | API base URL | | PORT | 3100 | HTTP server port (REST mode) |

Development

git clone https://github.com/scrumball/scrumball-influencer-plugins.git
cd scrumball-influencer-plugins
npm install

npm run dev              # REST server with hot reload
npm run dev:mcp          # MCP server (stdio)
npm run build            # Production build
npm run typecheck        # Type checking
npm run test             # Tests
npm run generate:openapi # Regenerate OpenAPI spec

Test locally with Claude Code:

claude --plugin-dir .

License

MIT