Query Taboola Realize campaigns and pull performance reports through natural language, straight from Claude Code. Powered by the Realize remote MCP.
Scope today: account discovery, campaign + item inspection, targeting / audience / publisher / conversion-rule lookup, and performance reports — all read-only. This plugin does not enable write operations; for write-intent requests (creating, editing, pausing, duplicating), the plugin walks you through the Realize console and then verifies the result via MCP.
- Claude Code CLI installed (
claude --versionworks) - A Taboola Realize account (you'll authenticate via Taboola SSO on first use)
- Network access to
https://mcp.realize.com/mcp
The plugin ships with the remote Realize MCP pre-wired. No local setup required — OAuth 2.1 is handled automatically by Claude Code.
Choose the path that matches how you consume Claude Code plugins:
claude plugin i realize-ads-apiThat single command installs everything — the realize-analyst agent, the skills, and the Realize MCP wiring. On the first tool call, Claude Code opens a browser for Taboola SSO to complete OAuth 2.1; after that you're ready to run prompts like "List my Realize accounts".
Requires the plugin to be registered with a Claude Code plugin marketplace your CLI has access to. See Claude Code plugin docs for the marketplace configuration specific to your Taboola distribution.
Clone the repo and load it as a local plugin via --plugin-dir:
git clone https://github.com/taboola/realize-claude-plugin
claude --plugin-dir ./realize-claude-pluginThis loads the skills, agent, and MCP wiring directly from the repo without requiring a marketplace install. Use this for iterating on skills, testing scenarios, or running the plugin inside a restricted/air-gapped environment.
On first tool call, Claude Code opens a browser for Taboola SSO login and returns you to the terminal once authenticated.
If you only want the remote Realize MCP and not the opinionated skills/agent this plugin provides:
claude mcp add --transport http --callback-port 3000 realize-mcp https://mcp.realize.com/mcp- OAuth 2.1 via Taboola SSO. On first tool call, your default browser opens to the Taboola login page. Enter your credentials; Claude Code stores the resulting token securely.
- No manual token management. Token refresh is handled by the transport layer.
- Multi-user safe. The remote endpoint is stateless and per-user — no shared credentials.
If you need to run Realize MCP locally (air-gapped dev, custom routing, etc.), install the Python package and configure client credentials:
pip install realize-mcpThen add to .mcp.json (or your Claude Code MCP config):
{
"mcpServers": {
"realize-mcp": {
"command": "realize-mcp-server",
"env": {
"REALIZE_CLIENT_ID": "your_client_id",
"REALIZE_CLIENT_SECRET": "your_client_secret"
}
}
}
}For self-hosted HTTP mode and full local deployment details, see the realize-mcp repo.
| Skill | Purpose |
|---|---|
accounts |
Find Realize accounts and capture the account_id every other tool needs |
campaigns |
List and inspect campaigns and their creatives |
discovery |
Look up targeting metadata, audiences, publishers, conversion rules, time zones, and CTA types — resolves opaque IDs before campaign work |
reports |
Pull the four Realize performance reports and interpret the CSV output |
optimize-campaign |
Diagnose underperforming campaigns against Taboola's official playbook (500–1000 clicks per item, $50/day minimum, 7–10 day learning phase) and prescribe concrete UI actions |
create-campaign |
Walk through the Realize console setup flow (exact Marketing Objective enum, Bid Strategy × budget minimums, learning-phase defaults) for write-intent actions, plus MCP verification afterward |
The plugin also ships one agent, realize-analyst, which routes natural-language questions to the right skill/tool and summarizes results in prose.
"List my Realize accounts."
"Show me the active campaigns for Acme."
"Which content drove the most spend in the last 7 days?"
"Break down spend by campaign for the last 30 days."
"Why is CPC up on campaign 12345 this week?"
"Show me the top 50 site/day rows for campaign 12345."
# optimization
"My campaign 12345 is burning budget with no conversions — what should I do?"
"Which items on campaign 67890 should I pause?"
"Which sites are wasting my spend this month?"
"My CPA doubled over the last two weeks. Help me diagnose."
# discovery (look up IDs / catalogs)
"What audiences are available for this account?"
"List all DMAs in the US."
"Show me publishers matching 'news' on this account."
"What time zones does Realize support?"
"What CTA button types exist for native items?"
# setup (UI walkthrough)
"Create a new Online Purchases campaign with a $25 CPA target."
"Walk me through launching a Leads campaign in the UK."
Points Claude Code at the remote Realize MCP. Usually nothing to edit.
Persist a default account between sessions:
---
default_account_id: advertiser_12345_prod
default_account_name: Example Advertiser
---The accounts skill offers to write this for you.
OAuth browser doesn't open.
Ensure port 3000 is free (the MCP transport uses it for the OAuth callback). Close any lingering process and retry.
search_accounts returns nothing.
Confirm you logged in to the correct Taboola SSO realm. If your org uses a non-default tenant, contact your Taboola account rep.
Reports come back with Records: 0.
The query window genuinely had no data, or you queried a campaign that didn't run in that window. Widen the date range or re-verify the campaign_id.
What format are account_id, campaign_id, and item_id in?
All three are opaque identifiers returned by the API. account_id is a string (e.g., advertiser_12345_prod) returned exclusively by search_accounts. campaign_id and item_id come from campaign/item tools. Pass them to follow-up calls exactly as received — don't reformat or coerce to numbers.
The plugin tried to create a campaign and failed.
Claude should route write-intent requests to the create-campaign skill (UI walkthrough) whenever no MCP tool exists for the requested action. If Claude attempted a tool call that doesn't exist or isn't documented, that's a bug — please file an issue with the transcript.
CSV output was truncated.
Very large result sets are auto-truncated server-side. Narrow the query (shorter date range, specific campaign_id, higher sort discrimination) and retry.
Please report security issues privately — see SECURITY.md.
Issues and PRs welcome — see CONTRIBUTING.md.