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

Clone or download this repository

Install dependencies

pip install -r requirements.txt

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

Log in to NewsBreak for Business
Navigate to your account settings
Go to the API section
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) ``bash python server.py --token YOUR_ACCESS_TOKEN ``

Method 1B: Using environment variable ```bash

Ensure .env file has NEWSBREAK_ACCESS_TOKEN set

python server.py ```

Method 1C: Using the run script ``bash ./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) ``json { "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 ``json { "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) ``json { "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

---

Built with FastMCP v2.13.0

NewsBreak Ads MCP Server