Skip to content

taboola/realize-mcp

BranchesTags

Repository files navigation

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 Streamable HTTP transport for multi-user deployment.

License Python MCP Latest Version

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 → Tools & MCP:

{
  "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"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add realize-mcp --transport stdio -e REALIZE_CLIENT_ID=your_client_id -e REALIZE_CLIENT_SECRET=your_client_secret -- realize-mcp-server

Option 2: Streamable HTTP Quick Start

HTTP-based Streamable HTTP transport supporting multiple users via OAuth 2.1. Runs in stateless mode — no session affinity required, k8s-friendly.

Server Installation

pip install realize-mcp

Start the Server

MCP_TRANSPORT=streamable-http OAUTH_DCR_CLIENT_ID=your_dcr_client_id realize-mcp-server

Client Setup

Claude Desktop

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

Claude Code (CLI)

claude mcp add --transport http --callback-port 3000 realize-mcp https://your-mcp-server.example.com/mcp

Cursor IDE - Add to Settings → Tools & MCP:

{
  "mcpServers": {
    "realize-mcp": {
      "type": "streamable-http",
      "url": "https://your-mcp-server.example.com/mcp"
    }
  }
}

Endpoints

  • GET /.well-known/oauth-protected-resource - RFC 9728 Protected Resource Metadata (supports path-based discovery)
  • GET /.well-known/oauth-authorization-server - RFC 8414 metadata (registration_endpoint rewritten)
  • POST /register - RFC 7591 Dynamic Client Registration
  • POST|GET|DELETE /mcp - MCP Streamable HTTP endpoint (requires Bearer token)
  • GET /health - Health check endpoint for Kubernetes probes
  • GET /metrics - Prometheus metrics endpoint

Tools Reference

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

Authentication (stdio only)

These tools are only available in stdio mode, where the server manages its own client credentials. In Streamable HTTP mode, authentication is handled at the transport layer via OAuth 2.1 so these tools are excluded.

get_auth_token — Authenticate with Realize API using client credentials (REALIZE_CLIENT_ID/REALIZE_CLIENT_SECRET).

get_token_details — Get details about the current authentication 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

Top Performing Content

User: "Show top 20 performing content items"
AI Process:
  get_top_campaign_content_report(
    account_id="account_id_from_search",
    start_date="2024-01-01",
    end_date="2024-01-31",
    page_size=20,
    sort_field="spent",
    sort_direction="DESC"
  )
  Result: Top content sorted by spend

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 Streamable HTTP transport:

  • OAuth Dynamic Client Registration client ID (OAUTH_DCR_CLIENT_ID)
  • Optional: OAUTH_SERVER_URL (defaults to https://authentication.taboola.com/authentication)
  • Publicly accessible server URL for OAuth callbacks
  • MCP_SERVER_SCHEME — defaults to https. Set to http for local dev without TLS.

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

Prometheus Metrics

Enabled by default (METRICS_ENABLED=true). Exposed at GET /metrics in Streamable HTTP mode.

Metric Type Labels
realize_mcp_http_requests_total Counter method, endpoint, http_status
realize_mcp_http_request_latency_seconds Histogram endpoint
realize_mcp_tool_calls_total Counter tool_name, status
realize_mcp_tool_call_latency_seconds Histogram tool_name
realize_mcp_client_connections_total Counter client_name, client_version
realize_mcp_api_requests_total Counter method, endpoint_pattern, http_status
realize_mcp_api_request_latency_seconds Histogram method, endpoint_pattern
realize_mcp_api_errors_total Counter method, endpoint_pattern, error_type

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.

About

No description, website, or topics provided.

Resources

Readme

License

Apache-2.0 license
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases 14

v1.0.20 Latest
Mar 19, 2026
+ 13 releases

Packages

 
 
 

Contributors

Languages