# SwipeBuilder MCP Server
Access your SwipeBuilder ad swipe library programmatically via the Model Context Protocol (MCP).
## Installation
### From PyPI (when published)
```bash
pip install swipebuilder-mcp
```
### From Source
```bash
cd swipebuilder-mcp
pip install -e .
```
## Configuration
### Get Your API Key
1. Log in to [SwipeBuilder](https://app.swipebuilder.io)
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):
```json
{
"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:
```bash
SWIPEBUILDER_API_KEY=sb_live_xxx swipebuilder-mcp
```
### With Docker
```bash
docker build -t swipebuilder-mcp .
docker run -e SWIPEBUILDER_API_KEY=sb_live_xxx swipebuilder-mcp
```
Or with docker-compose:
```bash
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
