# NewsBreak MCP Server

An MCP (Model Context Protocol) server that wraps the NewsBreak Advertising API, allowing you to manage advertising campaigns, ad sets, and ads programmatically.

## Features

### Campaign Management
- **Create Campaign** - Create new advertising campaigns with objectives like WEB_CONVERSION, APP_CONVERSION, REACH, WEB_TRAFFIC, APP_TRAFFIC
- **Get Campaigns** - List and search campaigns with filters
- **Update Campaign** - Modify campaign names
- **Update Campaign Status** - Enable/disable campaigns (ON/OFF)

### Ad Set Management
- **Create Ad Set** - Create ad sets with targeting, budgets, schedules, and bid strategies
- **Get Ad Sets** - List and filter ad sets by campaign, status, etc.
- **Update Ad Set** - Modify ad set configuration including targeting, budget, and schedule
- **Update Ad Set Status** - Enable/disable ad sets

### Ad Management
- **Create Ad** - Create ads with creative content (images, videos, GIFs)
- **Get Ads** - List and filter ads by campaign, ad set, or status
- **Update Ad** - Modify ad content and tracking URLs
- **Update Ad Status** - Enable/disable ads

### Asset Management
- **Upload Asset** - Upload images, videos, or GIFs to NewsBreak CDN for use in ads

## Installation

```bash
cd newsbreak-mcp-server
npm install
npm run build
```

## Configuration

Set the following environment variable:

```bash
export NEWSBREAK_ACCESS_TOKEN="your-access-token-here"
```

To get an access token, follow the NewsBreak API authentication process in the [NewsBreak Ad Manager](https://admanager.newsbreak.com/).

## Usage

### As a stdio MCP Server (default)

```bash
npm start
# or
node dist/index.js
```

### As an HTTP MCP Server

```bash
TRANSPORT=http PORT=3000 npm start
```

### Claude Desktop Configuration

Add to your Claude Desktop configuration file (`~/.config/claude/claude_desktop_config.json` on Linux/Mac or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "newsbreak": {
      "command": "node",
      "args": ["/path/to/newsbreak-mcp-server/dist/index.js"],
      "env": {
        "NEWSBREAK_ACCESS_TOKEN": "your-access-token-here"
      }
    }
  }
}
```

## Available Tools

### Account Tools

| Tool | Description |
|------|-------------|
| `newsbreak_get_ad_accounts` | Get all ad accounts for specified organizations |

### Campaign Tools

| Tool | Description |
|------|-------------|
| `newsbreak_create_campaign` | Create a new campaign |
| `newsbreak_get_campaigns` | List campaigns with optional filters |
| `newsbreak_update_campaign` | Update campaign name |
| `newsbreak_update_campaign_status` | Enable/disable a campaign |

### Ad Set Tools

| Tool | Description |
|------|-------------|
| `newsbreak_create_ad_set` | Create a new ad set with targeting and budget |
| `newsbreak_get_ad_sets` | List ad sets with optional filters |
| `newsbreak_update_ad_set` | Update ad set configuration |
| `newsbreak_update_ad_set_status` | Enable/disable an ad set |

### Ad Tools

| Tool | Description |
|------|-------------|
| `newsbreak_create_ad` | Create a new ad with creative content |
| `newsbreak_get_ads` | List ads with optional filters |
| `newsbreak_update_ad` | Update ad content and tracking |
| `newsbreak_update_ad_status` | Enable/disable an ad |

### Asset Tools

| Tool | Description |
|------|-------------|
| `newsbreak_upload_asset` | Upload image/video/GIF to NewsBreak CDN |

## Example Usage

### Create a Campaign

```json
{
  "tool": "newsbreak_create_campaign",
  "arguments": {
    "adAccountId": "123456789",
    "name": "Summer Sale Campaign",
    "objective": "WEB_CONVERSION"
  }
}
```

### Create an Ad Set with Targeting

```json
{
  "tool": "newsbreak_create_ad_set",
  "arguments": {
    "campaignId": "987654321",
    "name": "Women 25-44 Ad Set",
    "budgetType": "DAILY",
    "budget": 5000,
    "startTime": 1700000000,
    "endTime": 1735793459,
    "bidType": "TARGET_CPA",
    "bidRate": 1000,
    "trackingId": "event123",
    "targeting": {
      "gender": { "positive": ["female"] },
      "ageGroup": { "positive": ["25-30", "31-44"] },
      "location": { "positive": ["all"] }
    }
  }
}
```

### Create an Ad

```json
{
  "tool": "newsbreak_create_ad",
  "arguments": {
    "adSetId": "111222333",
    "name": "Summer Sale Banner",
    "creative": {
      "type": "IMAGE",
      "headline": "Summer Sale - 50% Off!",
      "assetUrl": "https://static.particlenews.com/nova/assets/123/image.jpg",
      "description": "Shop our biggest sale of the year",
      "callToAction": "Shop Now",
      "brandName": "MyBrand",
      "clickThroughUrl": "https://example.com/summer-sale"
    }
  }
}
```

## Targeting Options

The ad set targeting supports the following dimensions:

| Dimension | Description | Example Values |
|-----------|-------------|----------------|
| `location` | Geographic targeting | `"all"`, state/city codes |
| `gender` | Gender targeting | `"male"`, `"female"`, `"all"` |
| `ageGroup` | Age group targeting | `"18-24"`, `"25-30"`, `"31-44"`, `"45-54"`, `"55+"` |
| `language` | Language targeting | `"en_us"`, `"es"`, etc. |
| `interest` | Interest targeting | Category IDs or `"all"` |
| `os` | Operating system | `"android@5"`, `"ios@14"` |
| `manufacturer` | Device manufacturer | `"apple"`, `"samsung"`, `"all"` |
| `carrier` | Mobile carrier | Carrier codes or `"all"` |
| `network` | Network type | `"wifi"`, `"5g"`, `"4g"` |

Each dimension can have `positive` (include) and `negative` (exclude) arrays.

## Bid Types

| Bid Type | Description | Required Fields |
|----------|-------------|-----------------|
| `CPM` | Cost per 1000 impressions | `bidRate` |
| `CPC` | Cost per click | `bidRate` |
| `TARGET_CPA` | Target cost per acquisition | `bidRate`, `trackingId` |
| `TARGET_ROAS` | Target return on ad spend | `roas`, `trackingId` |
| `MAX_CONVERSION` | Maximize conversions | `trackingId` |
| `MAX_CONVERSION_VALUE` | Maximize conversion value | `trackingId` |

## API Reference

This MCP server wraps the [NewsBreak Advertising API](https://advertising-api.newsbreak.com/hc/en-us/categories/37825505060237-API-Reference).

## License

MIT