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
- Log in to SwipeBuilder
- Go to Settings > API Keys
- Create a new API key (starts with
sb_live_orsb_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 environmentplatform(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 swipeapi_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 environmentparent_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 collectionapi_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 collectionapi_key(optional): API key if not set via environmentlimit(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 monthcredits_limit: Monthly credit limitcredits_remaining: Credits still availableperiod_start: Start of billing periodperiod_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