Allows programmatic access to a library of saved Facebook ad swipes, enabling users to retrieve ads, filter by format (image, video, carousel), and organize them into collections.
Provides tools to retrieve and manage Google ad swipes, allowing for programmatic filtering by ad format and organization within the SwipeBuilder library.
Enables programmatic retrieval and management of Instagram ad swipes, with capabilities to filter by media format and organize items into folders.
Facilitates access to TikTok ad swipes, providing tools to filter saved ads by format and manage library collections via the Model Context Protocol.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@SwipeBuilder MCP ServerShow me my recent TikTok video ads"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SwipeBuilder MCP Server
Access your SwipeBuilder ad swipe library programmatically via the Model Context Protocol (MCP).
Installation
From PyPI (when published)
From Source
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 |
| Yes* | - | Your API key. Can also be passed per-tool call. |
| No |
| 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):
Restart Claude Desktop after updating the configuration.
With Other MCP Clients
Run the server directly:
With Docker
Or with docker-compose:
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