Realize MCP - Taboola

Interact with the Taboola advertising platform using natural language via the Taboola Realize API.

A Model Context Protocol (MCP) server providing read and write access to Taboola's Realize API. Enables AI assistants to analyze campaigns, retrieve performance data, generate reports, and manage campaigns and items through natural language. Runs as a Streamable HTTP server with OAuth 2.1 — connect to the hosted server, no local install required.

Connect to the hosted Realize MCP server usingStreamable HTTPtransport with OAuth 2.1. Multi-user, stateless, no local install required.

Prerequisite: Node.js 18+ (providesnpx). Install fromnodejs.orgor runbrew install node.

{ "mcpServers": { "realize-mcp": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.realize.com/mcp", "3000"] } } }

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

search_accounts— Search accounts by numeric ID or text query.Call this firstto getaccount_idvalues needed by all other tools. Results includecurrency,country, andtime_zone_nameso the LLM can pick the right budget amounts and timezone.

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)

A campaign holds budget, bidding, schedule, and targeting. It contains items.

list_campaigns— List campaigns for an account (one page per call).

account_id (string, required) page (integer, default: 1) min: 1 page_size (integer, default: 10) min: 1, max: 10 (hard cap)

get_campaign— Get specific campaign details.

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

get_campaign_reach_estimate— Estimate reach for a hypothetical campaign configuration before launch. Forecast from targeting + optional bid/budget, not from historical performance. Returns lower/upper bounds for impressions and/or monthly unique users.

account_id (string, required) campaign (object, required) Same targeting blocks as create_campaign / update_campaign below. Reach narrows as more inputs are added: targeting only → audience reach; + cpc (pricing_model=CPC) → narrowed by bid competitiveness; + spending_limit or daily_cap → additionally capped by impressions the budget can afford. estimation_types (array of string, optional) IMPRESSIONS | MONTHLY_USERS — omit for both

Campaign write tools (create_campaign,update_campaign)

Both tools accept the same scalars and targeting blocks. Scalars partial-merge; targeting blocks full-replace within block. New campaigns ship paused unlessis_active=trueis sent.

create_campaign: account_id, name, marketing_objective, branding_text, spending_limit_model, bid_strategy update_campaign: account_id, campaign_id

Scalars (all optional on update; the create-required ones above are mandatory on create):

name (string) marketing_objective (string enum) BRAND_AWARENESS | DRIVE_WEBSITE_TRAFFIC | LEADS_GENERATION | ONLINE_PURCHASES | MOBILE_APP_INSTALL branding_text (string) Brand name shown with ads spending_limit_model (string enum) NONE | MONTHLY | ENTIRE spending_limit (number) Budget amount in account's default currency daily_cap (number) Daily spend cap pricing_model (string enum) CPC | VCPM (default CPC; VCPM requires bid_strategy=FIXED) bid_strategy (string enum) SMART | FIXED | TARGET_CPA | MAX_CONVERSIONS | MAX_VALUE cpc (number) Bid amount in account's default currency (per-click for CPC; per-1000-viewable-impressions for VCPM) cpa_goal (number) Target cost per acquisition (TARGET_CPA only) cpc_cap (number) Upper bound on bids start_date (string) YYYY-MM-DD end_date (string) YYYY-MM-DD tracking_code (string) Query string appended to item URLs daily_ad_delivery_model (string enum) BALANCED | STRICT traffic_allocation_mode (string enum) OPTIMIZED | EVEN is_active (boolean) true to launch, false to pause

Targeting blocks (allobject, optional, full-replace within block):

country_targeting Classic country (codes from search_geos dimension=countries) region_country_targeting Classic region (codes from search_geos dimension=regions) dma_country_targeting Classic DMA — US-only (codes from search_geos dimension=dma) city_targeting Classic city (codes from search_geos dimension=cities) postal_code_targeting Classic postal code (codes from search_geos dimension=postal_codes) platform_targeting DESK | PHON | TBLT | TV | OTHR os_targeting OS family + version (versions via search_techno) browser_targeting Browser names from search_techno dimension=browsers connection_type_targeting WIFI activity_schedule Dayparting (time_zone via list_time_zones) conversion_rules Conversion rule attachments (rules via search_conversion_rules) publisher_targeting Publisher allow/block-list (search_publishers) publisher_bid_modifier Per-publisher CPC bid modifier contextual_segments_targeting Contextual segments (search_contextual_segments) audiences_targeting First-party + custom audiences (search_audiences) lookalike_audience_targeting Lookalike audiences (search_lookalike_audiences)

An item is a creative served under a campaign. Two types are supported: native (URL-crawled or manual headline/image/URL) and display (3P ad tag or 1P Realize-hosted asset).

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

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

create_native_item— Create a native item on a campaign.

account_id (string, required) campaign_id (string, required) url (string, required) Landing URL title (string, required) Headline description (string, required) Body thumbnail_url (string, required) Image URL branding_text (string) creative_name (string) Human-readable creative label shown in the Realize UI cta (object) {cta_type} — values from list_cta_types

update_native_item— Update specific fields on a native item. Send[]forverification_pixel/viewability_tagto clear.

account_id (string, required) campaign_id (string, required) item_id (string, required) url (string) title (string) description (string) thumbnail_url (string) branding_text (string) creative_name (string) Human-readable creative label shown in the Realize UI is_active (boolean) Pause/resume cta (object) {cta_type} verification_pixel (object) Tracking pixels (full-replace within block) viewability_tag (object) Viewability tag (full-replace within block)

Editability: items in PENDING_APPROVAL accept full edits; RUNNING / PAUSED accept onlyis_activetoggles plus minor metadata; REJECTED items cannot be edited (recreate).

create_display_item— Create a display item on a campaign. Send exactly one ofad_tag(3P third-party tag) orasset_url(1P Realize-hosted asset).

account_id (string, required) campaign_id (string, required) url (string, required) Landing URL creative_name (string, required) Human-readable creative label shown in the Realize UI ad_tag (string) 3P tag (raw HTML/JS). Pair with dimensions. dimensions (array of {width,height}) Required with ad_tag; rejected with asset_url. asset_url (string) 1P hosted asset URL (image/video/HTML5 zip). Realize ingests by file extension.

update_display_item— Update fields on a display item. Send[]forverification_pixel/viewability_tagto clear.

account_id (string, required) campaign_id (string, required) item_id (string, required) url (string) creative_name (string) is_active (boolean) Pause/resume ad_tag (string) Swap 3P tag; requires dimensions. dimensions (array of {width,height}) asset_url (string) Swap 1P hosted asset (re-ingest by file extension). verification_pixel (object) Tracking pixels (full-replace within block) viewability_tag (object) Viewability tag (full-replace within block)

Use these to populate campaign and item targeting fields with valid values.

search_geos— Countries, regions, DMAs, cities, postal codes. Returns{code, name}pairs; use thecodefield for targeting.

dimension (string enum, required) countries | regions | dma | cities | postal_codes country_code (string) Required for regions / dma / cities / postal_codes

search_techno— OS versions and browsers.

dimension (string enum, required) operating_system_versions | browsers os_family (string) Required for operating_system_versions

search_audiences— First-party and custom audiences for an account.

account_id (string, required) country_codes (string) country_targeting_type (string enum) ALL | INCLUDE | EXCLUDE

search_lookalike_audiences— CRM / pixel / PBP lookalike audiences.

account_id (string, required) country_code (string)

search_contextual_segments— Contextual segments.

account_id (string, required) country_codes (string) country_targeting_type (string enum) ALL | INCLUDE | EXCLUDE

search_publishers— Publishers an account may target.

account_id (string, required) query (string, required) publisher_ids (array) page (integer, default: 1) min: 1 page_size (integer, default: 10) min: 1, max: 50

search_conversion_rules— Conversion rules attached to an account.

list_time_zones— IANA time-zone names foractivity_schedule.time_zone. No parameters.

list_cta_types—cta.cta_typevalues forcreate_native_item/update_native_item. No parameters.

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 enum) clicks | spent | impressions sort_direction (string enum, default: DESC) ASC | DESC filters (object) JSON object with string values only

get_top_campaign_content_report— Top performing campaign content. Supports: shared params only. Not paginated and not sortable — returns the full result set in a single call, fixed-sorted by revenue DESC (thespentcolumn), capped at top 1000 server-side.

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

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

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

Reports return flattened rows. Each report has a fixedrow grain(the composite key that makes a row unique). The samesite_idcan appear under several campaigns, so rows must be read at their grain — not merged by a single id. Column names below are the literal CSV headers (note: campaign id iscampaignin the performance reports butcampaign_idin the history report).

get_campaign_breakdown_report campaign get_campaign_site_day_breakdown_report (campaign, site_id, date) get_top_campaign_content_report (campaign, item) get_campaign_history_report (campaign_id, change_time, id) # audit log, not metrics

Don't rely on column position — grain/key columns aren't guaranteed to lead or be adjacent. Each response names the row key explicitly on aRow key:line, the authoritative set of columns that makes a row unique.

Metrics are computed server-side(performance reports only).ctr,cpc,cpm,cpa,cvr,roasare pre-computed per row — read them as-is. Do not recompute or average them across rows. To aggregate volume, sum only the raw counters (clicks,impressions,spent).

get_campaign_history_reportis a change/audit log, not a performance report — one row per change event (change_type,old_value→new_value,performer). It has no impression/click/spend or rate metrics.

Cross-account:reports are scoped to the singleaccount_idqueried and do not roll up child accounts; query each child account separately. Campaign/site/item ids are globally unique, so no account column is needed in the grain.

- TheTotalin the summary line is authoritative — do not sum rows across pages to derive totals or rates.

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 gettingaccount_idvalues fromsearch_accountsfirst - never use numeric IDs directly.

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

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

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

User: "Bump the daily cap on Marketing Corp's Spring Sale campaign to $500" AI Process: Step 1: search_accounts("Marketing Corp") → account_id: "mktg_corp_001" Step 2: list_campaigns(account_id="mktg_corp_001") → find Spring Sale → campaign_id: "12345678" Step 3: update_campaign( account_id="mktg_corp_001", campaign_id="12345678", daily_cap=500 ) Result: Campaign updated; other fields and targeting untouched

User: "How many people could we reach on desktop in the US for Marketing Corp?" AI Process: Step 1: search_accounts("Marketing Corp") → account_id: "mktg_corp_001" Step 2: get_campaign_reach_estimate( account_id="mktg_corp_001", campaign={ "country_targeting": {"type": "INCLUDE", "value": ["US"]}, "platform_targeting": {"type": "INCLUDE", "value": ["DESK"]} }, estimation_types=["IMPRESSIONS", "MONTHLY_USERS"] ) Result: Lower/upper bound estimates for impressions and monthly unique users

User: "Add a new ad to campaign 12345678 pointing at example.com/landing — headline 'Save 20% This Spring', body 'Limited-time offer on all spring collection items.', thumbnail https://cdn.example.com/spring.jpg, Shop Now CTA" AI Process: Step 1: search_accounts(...) → account_id: "mktg_corp_001" Step 2: list_cta_types() → confirm "SHOP_NOW" is a valid cta_type Step 3: create_native_item( account_id="mktg_corp_001", campaign_id="12345678", url="https://example.com/landing", title="Save 20% This Spring", description="Limited-time offer on all spring collection items.", thumbnail_url="https://cdn.example.com/spring.jpg", cta={"cta_type": "SHOP_NOW"} ) Result: Native item created

- 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 byclicks,spent, orimpressions
- Size Optimization: Automatic truncation for large datasets

For product or security concerns, bug reports, and feature requests, open an issue atgithub.com/taboola/realize-mcp/issues.

Realize MCP accesses the Realize API using your OAuth credentials and returns data only to your connected MCP client. Information processed in connection with your use of Realize MCP is handled in accordance with theTaboola Privacy Policy.