Realize MCP Server

A Model Context Protocol (MCP) server that provides read-only access to Taboola's Realize API, enabling AI assistants to analyze campaigns, retrieve performance data, and generate reports through natural language. Install the MCP Server with stdio transport for single-user local use, or SSE transport for multi-user deployment.

Option 1: Stdio Quick Start

Standard MCP transport for local clients. The server runs on your machine and uses server-side credentials for Taboola API authentication.

Server Installation

pip install realize-mcp

Client Setup

Cursor IDE - Add to Settings → Features → Model Context Protocol:

{
  "mcpServers": {
    "realize-mcp": {
      "command": "realize-mcp-server",
      "env": {
        "REALIZE_CLIENT_ID": "your_client_id",
        "REALIZE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Claude Desktop - Add to claude_desktop_config.json:

{
  "mcpServers": {
    "realize-mcp": {
      "command": "realize-mcp-server",
      "env": {
        "REALIZE_CLIENT_ID": "your_client_id",
        "REALIZE_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Option 2: SSE Quick Start

HTTP-based Server-Sent Events (SSE) transport supporting multiple users via OAuth 2.1

Server Installation

git clone https://github.com/taboola/realize-mcp.git
cd realize-mcp

# Set required credentials
export OAUTH_DCR_CLIENT_ID=your_dcr_client_id
export OAUTH_DCR_CLIENT_SECRET=your_dcr_client_secret
export MCP_SERVER_URL=https://your-mcp-server.example.com

# Run the SSE server
./scripts/run-sse.sh

Client Setup

Claude Desktop

Go to Settings → Connectors → Add Custom Connector
Enter the MCP Server name and URL (e.g., https://your-mcp-server.example.com/sse)
Select Connect to initiate the OAuth 2.1 flow
A browser window will open to Taboola SSO—enter your credentials to obtain a bearer token used by Realize tools

Cursor IDE

⚠️ Temporarily unavailable — blocked by Cursor OAuth redirect bug.

SSE Endpoints

GET /.well-known/oauth-protected-resource - RFC 9728 metadata
GET /.well-known/oauth-authorization-server - RFC 8414 metadata (proxied)
GET /authorize - Redirects to upstream auth server
POST /register - RFC 7591 Dynamic Client Registration
POST /oauth/token - Token endpoint (proxied to auth server)
POST /token - Alternative token endpoint
GET /sse - SSE connection endpoint (requires Bearer token)
POST /messages - MCP protocol message handling
GET /health - Health check endpoint for Kubernetes probes

Tools Reference

All 12 tools are read-only. No create/update/delete operations.

Authentication

get_auth_token — Authenticate with Realize API using client credentials. No parameters. Requires REALIZE_CLIENT_ID and REALIZE_CLIENT_SECRET env vars.

get_token_details — Get details about the current authentication token. No parameters. Requires a valid token from get_auth_token.

Account Management

search_accounts — Search accounts by numeric ID or text query. Call this first to get account_id values needed by all other tools.

query       (string, required)            Cannot be empty. Numeric = exact ID; text = fuzzy name
page        (integer, default: 1)         min: 1
page_size   (integer, default: 10)        min: 1, max: 10 (hard cap)

Campaign Management

All campaign tools require account_id (string from search_accounts), not a raw numeric ID. No pagination — all results returned in a single response.

get_all_campaigns — List all campaigns for an account.

account_id  (string, required)

get_campaign — Get specific campaign details.

account_id  (string, required)
campaign_id (string, required)

get_campaign_items — Get all items/creatives for a campaign.

account_id  (string, required)
campaign_id (string, required)

get_campaign_item — Get a specific campaign item's details.

account_id  (string, required)
campaign_id (string, required)
item_id     (string, required)

Reporting (CSV Format)

All report tools return CSV with a summary header. Every report requires these parameters:

account_id  (string, required)            From search_accounts
start_date  (string, required)            Format: YYYY-MM-DD
end_date    (string, required)            Format: YYYY-MM-DD
page        (integer, default: 1)         min: 1
page_size   (integer, default: 20)        min: 1, max: 100

Some reports also support sorting and filtering:

sort_field      (string, optional)        Allowed: clicks, spent, impressions
sort_direction  (string, default: DESC)   Allowed: ASC, DESC
filters         (object, optional)        JSON object with string values only

get_top_campaign_content_report — Top performing campaign content. Supports: shared params + sort.

get_campaign_breakdown_report — Campaign performance breakdown. Supports: shared params + sort + filters.

get_campaign_history_report — Historical campaign data. Supports: shared params only (no sort, no filters).

get_campaign_site_day_breakdown_report — Site/day performance breakdown. Supports: shared params + sort + filters.

Usage Examples

Basic Usage

User: "Show me campaigns for Marketing Corp"
AI:
  1. Searches accounts for "Marketing Corp"
  2. Retrieves campaigns using the found account_id
  3. Returns campaign list with performance metrics

Important: All operations require getting account_id values from search_accounts first - never use numeric IDs directly.

Find Account and List Campaigns

User: "Show campaigns for account 12345"
AI Process:
  Step 1: search_accounts("12345") → Returns account_id: "advertiser_12345_prod"
  Step 2: get_all_campaigns(account_id="advertiser_12345_prod")
  Result: List of campaigns with details

Get Performance Report

User: "Get campaign performance for Marketing Corp last month"
AI Process:
  Step 1: search_accounts("Marketing Corp") → account_id: "mktg_corp_001"
  Step 2: get_campaign_breakdown_report(
    account_id="mktg_corp_001",
    start_date="2024-01-01",
    end_date="2024-01-31"
  )
  Result: CSV report with campaign metrics

Prerequisites

Common:

Python 3.10+ (Python 3.11+ recommended)
MCP-compatible client (Claude Desktop, Cursor, VS Code, etc.)

For stdio transport:

Taboola Realize API credentials (REALIZE_CLIENT_ID and REALIZE_CLIENT_SECRET)

For SSE transport:

OAuth Dynamic Client Registration credentials (OAUTH_DCR_CLIENT_ID and OAUTH_DCR_CLIENT_SECRET)
Publicly accessible server URL for OAuth callbacks

Important Workflow Notes

Account ID Requirement

All campaign and report tools require account_id values from search_accounts:

✅ Correct Workflow:

1. search_accounts("company name" or "numeric_id")
2. Extract account_id from response
3. Use account_id in other tools

❌ Incorrect:

get_all_campaigns(account_id="12345")  # Numeric IDs won't work

Report Features

CSV Format: Reports return efficient CSV data with headers and pagination info
Pagination: Default page_size=20, max=100 to prevent overwhelming responses
Sorting: Available for most reports by clicks, spent, or impressions
Size Optimization: Automatic truncation for large datasets

Troubleshooting

Test the server manually:

REALIZE_CLIENT_ID=test REALIZE_CLIENT_SECRET=test realize-mcp-server

You should see: INFO:realize.realize_server:Starting Realize MCP Server...

Detailed Documentation

For comprehensive information, see design.md:

Recent Fixes & Version History - Detailed release notes and upgrade instructions
Installation Options - PyPI & Source installation with troubleshooting
Architecture & Design Principles - Technical implementation details
Advanced Features - CSV format, pagination, sorting, and optimization
Development Guide & Testing - Setup, testing, and contribution guidelines
Comprehensive Troubleshooting - Detailed solutions for common issues
Security Best Practices - Credential management and operational security
Complete API Reference - Full technical API documentation
Technology Stack Details - Dependencies and system requirements

License

Licensed under the Apache License 2.0. See LICENSE for details.

Realize MCP Server - Safe, efficient, read-only access to Taboola's advertising platform through natural language.

Name		Name	Last commit message	Last commit date
Latest commit History 37 Commits
scripts		scripts
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
design.md		design.md
env.template		env.template
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Realize MCP Server

Option 1: Stdio Quick Start

Server Installation

Client Setup

Option 2: SSE Quick Start

Server Installation

Client Setup

SSE Endpoints

Tools Reference

Authentication

Account Management

Campaign Management

Reporting (CSV Format)

Usage Examples

Basic Usage

Find Account and List Campaigns

Get Performance Report

Top Performing Content

Prerequisites

Important Workflow Notes

Account ID Requirement

Report Features

Troubleshooting

Detailed Documentation

License

About

Uh oh!

Releases 3

Packages

Contributors 4

Uh oh!

Languages

License

taboola/realize-mcp

Folders and files

Latest commit

History

Repository files navigation

Realize MCP Server

Option 1: Stdio Quick Start

Server Installation

Client Setup

Option 2: SSE Quick Start

Server Installation

Client Setup

SSE Endpoints

Tools Reference

Authentication

Account Management

Campaign Management

Reporting (CSV Format)

Usage Examples

Basic Usage

Find Account and List Campaigns

Get Performance Report

Top Performing Content

Prerequisites

Important Workflow Notes

Account ID Requirement

Report Features

Troubleshooting

Detailed Documentation

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Packages 0

Contributors 4

Uh oh!

Languages

Packages