SwipeBuilder MCP Server

Access your SwipeBuilder ad swipe library programmatically via the Model Context Protocol (MCP).

Installation

From PyPI (when published)

pip install swipebuilder-mcp

From Source

cd swipebuilder-mcp
pip install -e .

Configuration

Get Your API Key

1. Log in to SwipeBuilder
2. Go to Settings > API Keys
3. Create a new API key (starts with sb_live_ or sb_test_)

Environment Variables

Variable	Required	Default	Description
SWIPEBUILDER_API_KEY	Yes*	-	Your API key. Can also be passed per-tool call.
SWIPEBUILDER_API_URL	No	https://api.swipebuilder.io/v1	API base URL (for testing)

Usage

With Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "swipebuilder": {
      "command": "swipebuilder-mcp",
      "env": {
        "SWIPEBUILDER_API_KEY": "sb_live_your_key_here"
      }
    }
  }
}

Restart Claude Desktop after updating the configuration.

With Other MCP Clients

Run the server directly:

SWIPEBUILDER_API_KEY=sb_live_xxx swipebuilder-mcp

With Docker

docker build -t swipebuilder-mcp .
docker run -e SWIPEBUILDER_API_KEY=sb_live_xxx swipebuilder-mcp

Or with docker-compose:

SWIPEBUILDER_API_KEY=sb_live_xxx docker-compose up

Available Tools

get_swipes

Retrieve ads from your swipe file with optional filters.

Parameters:

• api_key (optional): API key if not set via environment
• platform (optional): Filter by platform (facebook, tiktok, instagram, linkedin, google)
• format (optional): Filter by format (image, video, carousel)
• limit (optional): Number of results, 1-100 (default: 50)
• cursor (optional): Pagination cursor from previous response

Credit Usage: 1 credit per swipe returned

get_swipe

Get a single swipe by ID.

Parameters:

• swipe_id (required): The ID of the swipe
• api_key (optional): API key if not set via environment

Credit Usage: 1 credit

get_collections

List your collections (folders).

Parameters:

• api_key (optional): API key if not set via environment
• parent_id (optional): Filter by parent ('root' for root-level, collection ID for children)
• limit (optional): Number of results, 1-100 (default: 50)
• cursor (optional): Pagination cursor

Credit Usage: No credits consumed

get_collection

Get a single collection by ID.

Parameters:

• collection_id (required): The ID of the collection
• api_key (optional): API key if not set via environment

Credit Usage: No credits consumed

get_collection_items

Get items (swipes) within a specific collection.

Parameters:

• collection_id (required): The ID of the collection
• api_key (optional): API key if not set via environment
• limit (optional): Number of results, 1-100 (default: 50)
• cursor (optional): Pagination cursor

Credit Usage: 1 credit per swipe returned

get_usage

Check your API credit usage for the current billing period.

Parameters:

• api_key (optional): API key if not set via environment

Credit Usage: No credits consumed

Returns:

• credits_used: Credits consumed this month
• credits_limit: Monthly credit limit
• credits_remaining: Credits still available
• period_start: Start of billing period
• period_end: End of billing period

Example Conversations

Once configured, you can ask Claude things like:

• "Show me my recent Facebook video ads"
• "Get all swipes from my 'Winners' collection"
• "How many API credits have I used this month?"
• "Find all carousel ads I've saved"

Rate Limits

• 100 requests per minute
• 1,000 requests per hour

If you exceed these limits, you'll receive a rate limit error.

Credits

Each API call that returns swipe data consumes credits:

• 1 credit per swipe returned from any endpoint
• Collections and usage queries are free (no credits)

Check your plan for monthly credit limits.

Support

• Documentation: https://docs.swipebuilder.io/api
• Support: support@swipebuilder.io

License

MIT