# 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