SwipeBuilder

You can access and manage your SwipeBuilder ad swipe library programmatically by running a lightweight MCP server. It lets you fetch swipes, collections, and usage credits from your swipe library through simple commands from any MCP-capable client. This guide shows you how to install, configure, and use the server with your clients.

How to use

Your MCP server runs locally as a small service that your MCP clients can talk to. Start it with your API key set in the environment, and then issue requests through a client that understands the MCP protocol. You can retrieve swipes, collections, and usage data, and you can filter results by platform, format, or collection.

Typical workflows include fetching the latest swipes for a given platform, listing items within a collection, checking how many credits you have used this month, and listing which swipes exist in a particular collection. Each swipe you request counts toward your credits as described in the credits section.

How to install

Prerequisites: you need Python and pip installed on your system.

# Install from PyPI when available
pip install swipebuilder-mcp

# Or install from source
cd swipebuilder-mcp
pip install -e .

Configuration and usage notes

Get your API key from your SwipeBuilder account under Settings > API Keys. The key starts with sb_live_ or sb_test_. You will pass this key to the MCP server either via environment variables or per-tool invocation.

Environment variables you will use:

SWIPEBUILDER_API_KEY=sb_live_your_key_here
SWIPEBUILDER_API_URL=https://api.swipebuilder.io/v1  # optional, defaults to the production URL

With Claude Desktop

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

With Other MCP Clients

Run the server directly in your environment using the API key you created.

SWIPEBUILDER_API_KEY=sb_live_xxx swipebuilder-mcp

With Docker

You can also run the MCP server inside Docker by passing your API key as an environment variable.

docker run -e SWIPEBUILDER_API_KEY=sb_live_xxx swipebuilder-mcp

Notes on security and usage

Treat your API key as a secret. Do not expose it in public logs or shared configurations. You can also pass the API key per-tool if your client supports that pattern.

Credits and rate limits

Rate limits are 100 requests per minute and 1,000 requests per hour. Each swipe data response consumes 1 credit. Collections and usage queries are free.

Supported tools and endpoints

You can access the following endpoints to manage and retrieve swipes and collections.

Example conversations you can try

Ask for recent items in a platform, or fetch items from a specific collection. You can also check your credits for the current billing period.

Troubleshooting

If you encounter authentication errors, verify that SWIPEBUILDER_API_KEY is set correctly in your environment or per-tool invocation. Ensure you are using a valid API key (sb_live_ or sb_test_). If you hit rate limit errors, slow down request frequency or request fewer items per call.

Support

For API reference and support, reach out to the SwipeBuilder team at support@swipebuilder.io.

Available tools

get_swipes

Retrieve ads from your swipe file with optional filters like platform, format, and limit. Credits: 1 per swipe returned.

get_swipe

Get a single swipe by its ID. Credits: 1 per swipe returned.

get_collections

List your collections (folders) with optional parent and pagination. Credits: none.

get_collection

Get a single collection by ID. Credits: none.

get_collection_items

Get items within a specific collection with optional limit and cursor. Credits: 1 per swipe returned.

get_usage

Check your current API credit usage for the billing period. Credits: none.