NewsBreak Ads MCP Server

A Model Context Protocol (MCP) server for the NewsBreak Business API, built with FastMCP. This server provides tools and resources for analytics, reporting, and campaign management through the NewsBreak advertising platform.

Features

MCP Tools

The server provides the following tools for interacting with NewsBreak's advertising API:

Analytics & Reporting (Primary Focus)

• get_ad_accounts - Retrieve ad accounts for specified organization IDs
• get_campaigns - List campaigns with filtering and pagination support
• get_tracking_events - Access pixel and postback tracking events
• run_performance_report - Generate synchronous performance reports with custom metrics and dimensions
• get_campaign_summary - Quick overview of recent campaign performance

MCP Resources

Read-only resources available through URI templates:

• accounts://{org_id}/ad-accounts - Ad accounts for an organization
• campaigns://{ad_account_id}/active - Active campaigns for an ad account
• events://{ad_account_id}/tracking - Tracking events for an ad account

Prerequisites

• Python 3.10 or higher
• NewsBreak for Business account
• NewsBreak API Access Token

Installation

1. Clone or download this repository

2. Install dependencies

pip install -r requirements.txt

3. Configure environment variables

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your NewsBreak access token:

NEWSBREAK_ACCESS_TOKEN=your_access_token_here

Obtaining Your Access Token

1. Log in to NewsBreak for Business
2. Navigate to your account settings
3. Go to the API section
4. Generate or copy your access token

Usage

The server supports multiple authentication methods and transport options.

Command-Line Options

python server.py --help

Options:
  --token TOKEN        NewsBreak API access token (overrides environment variable)
  --transport {stdio,http,sse}
                       Transport method (default: stdio)
  --host HOST         Host for HTTP/SSE transport (default: localhost)
  --port PORT         Port for HTTP/SSE transport (default: 8000)
  --version           Show version and exit

Option 1: Local Development (STDIO)

Method 1A: Using command-line argument (RECOMMENDED)

python server.py --token YOUR_ACCESS_TOKEN

Method 1B: Using environment variable

# Ensure .env file has NEWSBREAK_ACCESS_TOKEN set
python server.py

Method 1C: Using the run script

./run_server.sh

Option 2: Claude Desktop Integration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Method 2A: Pass token via command-line argument (RECOMMENDED - more secure)

{
  "mcpServers": {
    "newsbreak-ads": {
      "command": "python",
      "args": [
        "/path/to/newsbreak-ads-mcp-server/server.py",
        "--token",
        "your_access_token_here"
      ]
    }
  }
}

Method 2B: Pass token via environment variable

{
  "mcpServers": {
    "newsbreak-ads": {
      "command": "python",
      "args": [
        "/path/to/newsbreak-ads-mcp-server/server.py"
      ],
      "env": {
        "NEWSBREAK_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

Method 2C: Use .env file (most secure - no token in config)

{
  "mcpServers": {
    "newsbreak-ads": {
      "command": "python",
      "args": [
        "/path/to/newsbreak-ads-mcp-server/server.py"
      ]
    }
  }
}

Note: Requires .env file with NEWSBREAK_ACCESS_TOKEN in the project directory

Restart Claude Desktop after updating the configuration.

Option 3: HTTP Server

Run as an HTTP server for remote access:

# Using command-line token
python server.py --token YOUR_TOKEN --transport http --port 8000

# Or using environment variable
python server.py --transport http --port 8000 --host 0.0.0.0

# Or using fastmcp CLI
fastmcp run server.py --transport http --port 8000

Server will be available at: http://localhost:8000/mcp

Option 4: FastMCP Cloud

Deploy to FastMCP Cloud for instant HTTPS endpoints:

# Make sure to set NEWSBREAK_ACCESS_TOKEN in cloud environment
fastmcp deploy --config fastmcp_cloud.json

Example Usage

Get Ad Accounts

# In Claude or through MCP client
use_mcp_tool(
    server="newsbreak-ads",
    tool="get_ad_accounts",
    arguments={
        "org_ids": ["123456789"]
    }
)

Run Performance Report

use_mcp_tool(
    server="newsbreak-ads",
    tool="run_performance_report",
    arguments={
        "ad_account_id": "987654321",
        "date_from": "2024-01-01",
        "date_to": "2024-01-31",
        "dimensions": ["date", "campaign_id"],
        "metrics": ["impressions", "clicks", "spend", "conversions"],
        "level": "campaign"
    }
)

Get Campaign Summary

use_mcp_tool(
    server="newsbreak-ads",
    tool="get_campaign_summary",
    arguments={
        "ad_account_id": "987654321",
        "days": 7
    }
)

Access Resource

read_resource(
    uri="campaigns://987654321/active"
)

Available Tools

get_ad_accounts(org_ids: List[str])

Retrieves all ad accounts for specified organization IDs.

Parameters:

• org_ids: List of organization IDs

Returns: JSON with organizations and their ad accounts

get_campaigns(ad_account_id: str, page_no: int = 1, page_size: int = 50, search: Optional[str] = None, online_status: Optional[str] = None)

Lists campaigns with optional filtering and pagination.

Parameters:

• ad_account_id: Target ad account ID
• page_no: Page number (default: 1)
• page_size: Results per page - options: 5, 10, 20, 50, 100, 200, 500 (default: 50)
• search: Optional search query
• online_status: Filter by status (WARNING, INACTIVE, ACTIVE, DELETED)

Returns: JSON with campaigns and pagination info

get_tracking_events(ad_account_id: str, os_filter: Optional[str] = None)

Retrieves tracking events (pixels and postbacks) for an ad account.

Parameters:

• ad_account_id: Target ad account ID
• os_filter: Optional OS filter ("IOS", "ANDROID", or "" for web)

Returns: JSON with tracking events

run_performance_report(ad_account_id: str, date_from: str, date_to: str, dimensions: Optional[List[str]] = None, metrics: Optional[List[str]] = None, level: Optional[str] = None)

Generates a synchronous performance report.

Parameters:

• ad_account_id: Target ad account ID
• date_from: Start date (YYYY-MM-DD)
• date_to: End date (YYYY-MM-DD)
• dimensions: Optional dimensions (e.g., ["date", "campaign_id"])
• metrics: Optional metrics (e.g., ["impressions", "clicks", "spend"])
• level: Report level ("campaign", "ad_set", "ad")

Returns: JSON with report data

get_campaign_summary(ad_account_id: str, days: int = 7)

Quick summary of recent campaign performance.

Parameters:

• ad_account_id: Target ad account ID
• days: Number of days to look back (default: 7)

Returns: JSON with campaign summary

Architecture

The server is built with the following components:

• server.py - Main FastMCP server with tools and resources
• client.py - NewsBreak API client wrapper with authentication and rate limiting
• models.py - Pydantic data models for type safety and validation
• fastmcp.json - FastMCP deployment configuration
• .env - Environment variables (not committed to git)

Key Features

• Rate Limiting: Built-in rate limiter (10 requests/second by default)
• Error Handling: Automatic retry with exponential backoff
• Type Safety: Full Pydantic model validation
• Async/Await: High-performance async operations
• Environment-based Config: Secure credential management

API Reference

This server implements the following NewsBreak Business API endpoints:

• GET /v1/ad-account/getGroupsByOrgIds - Get ad accounts
• GET /v1/campaign/getList - List campaigns
• GET /v1/event/getList/{adAccountId} - Get tracking events
• POST /v1/report/runSync - Run synchronous report

Base URL: https://business.newsbreak.com/business-api/v1

Authentication: Access-Token header

For complete API documentation, visit: https://business.newsbreak.com/business-api-doc/docs/overview/

Troubleshooting

"NEWSBREAK_ACCESS_TOKEN environment variable not set"

Make sure you've created a .env file with your access token or set it in your environment:

export NEWSBREAK_ACCESS_TOKEN=your_token_here

"NewsBreak API error: Invalid token"

Your access token may be expired or invalid. Generate a new one from your NewsBreak for Business account.

Rate Limiting

The client includes built-in rate limiting (10 req/s). If you need to adjust this:

client = NewsBreakClient(access_token="...", rate_limit=5)  # 5 requests per second

Connection Timeouts

Default timeout is 30 seconds. Adjust if needed:

client = NewsBreakClient(access_token="...", timeout=60.0)  # 60 seconds

Development

Project Structure

newsbreak-ads-mcp-server/
├── server.py                   # Main MCP server
├── client.py                   # API client wrapper
├── models.py                   # Pydantic models
├── requirements.txt            # Python dependencies
├── fastmcp.json               # STDIO deployment config
├── fastmcp_cloud.json         # Cloud deployment config
├── claude_desktop_config.json # Claude Desktop example
├── run_server.sh              # Local run script
├── .env.example               # Environment template
├── .env                       # Your credentials (gitignored)
├── .gitignore
└── README.md

Running Tests

# Install dev dependencies
pip install pytest pytest-asyncio httpx

# Run tests (when implemented)
pytest

Contributing

Contributions are welcome! Areas for enhancement:

• [ ] Add support for asynchronous reports
• [ ] Implement custom report creation
• [ ] Add ad set and ad management tools
• [ ] Create comprehensive test suite
• [ ] Add more resource templates
• [ ] Implement webhook support
• [ ] Add caching layer for frequently accessed data

License

MIT License - feel free to use and modify as needed.

Support

For issues with:

• This MCP server: Open an issue in this repository
• NewsBreak API: Contact NewsBreak support through your business account
• FastMCP framework: Visit https://github.com/jlowin/fastmcp

Links

• NewsBreak for Business
• NewsBreak API Documentation
• FastMCP Documentation
• Model Context Protocol

---

Built with FastMCP v2.13.0