@ideepakrajput/taboola-write-mcp

Write-capable Model Context Protocol (MCP) server for the Taboola Backstage API — separate from Taboola’s official Realize MCP (Realize API). Use this package from Cursor, Claude Desktop, Claude Code, or any MCP host that supports stdio servers.

Disclaimer — not official

This project is not affiliated with, endorsed by, or supported by Taboola. It is an independent, community-maintained integration. Taboola’s trademarks and APIs belong to Taboola.

• No warranty: Software is provided “as is”. You are responsible for how you use it, for complying with Taboola’s terms and API policies, and for any changes you make to live campaigns or accounts.
• Publishing: Publishing this package or derived works online does not imply Taboola’s approval. Do not present it as an official Taboola product. Authors and contributors are not liable for misuse, API outages, data loss, billing impact, or policy violations arising from use of this MCP server.

Related — official Taboola Realize MCP (read + Realize API)

Taboola maintains realize-mcp on GitHub: the official MCP server for the Realize API. It is the right choice for account search, listing campaigns and items, CSV performance reports, geo/audience/publisher discovery tools, and managed campaign/item updates on that platform. Install via PyPI as realize-mcp; it supports stdio (local credentials: REALIZE_CLIENT_ID / REALIZE_CLIENT_SECRET) and Streamable HTTP (e.g. remote https://mcp.realize.com/mcp with OAuth 2.1, as in their docs).

| | realize-mcp (official) | This package | |---|--------|--------------| | Maintainer | Taboola | Independent (see disclaimer above) | | API surface | Realize | Backstage | | Typical credentials | REALIZE_* (stdio) or OAuth (HTTP) | TABOOLA_CLIENT_ID / TABOOLA_CLIENT_SECRET | | Transport | stdio, Streamable HTTP | stdio only (npx / node) | | Strengths | Reports, discovery, official Realize read/write flows | Backstage-focused write tools listed below |

You may configure both MCP servers in Cursor or Claude Desktop if you rely on Realize and Backstage separately. This npm package is not realize-mcp and does not use the hosted Realize MCP URL.

Features

• OAuth2 client credentials against Taboola Backstage.
• Safety: destructive/write tools require confirm=true.
• DRY_RUN=true: preview payloads without calling the API.
• Audit logs: successful writes append to writes.jsonl; API errors append to taboola-api-errors.jsonl under a stable data directory (see Logs & data directory).

Requirements

• Node.js ≥ 20
• Taboola client ID and client secret with Backstage API access

Environment variables

| Variable | Required | Description | |----------|----------|-------------| | TABOOLA_CLIENT_ID | Yes | OAuth client ID | | TABOOLA_CLIENT_SECRET | Yes | OAuth client secret | | TABOOLA_BASE_URL | No | Default https://backstage.taboola.com | | DRY_RUN | No | Set true to log payloads only | | TABOOLA_MCP_DATA_DIR | No | Override directory for log files (see below) |

Optional .env at the package root is loaded when present (works when running the built dist/ entry from npm).

Install & run

Option A — npm / npx (recommended for MCP clients)

After publishing, install or run without cloning:

npx -y @ideepakrajput/taboola-write-mcp

Ensure TABOOLA_CLIENT_ID and TABOOLA_CLIENT_SECRET are set in the MCP config env block (below).

Option B — from a git clone

npm install
cp .env.example .env   # edit with your credentials
npm run build
npm start

MCP configuration

Any client that supports MCP over stdio can use this server: pass command, args, and env. Paths below assume Option A (npx); for Option B, replace args with the absolute path to dist/index.js.

Cursor

Add a server in Cursor MCP settings (e.g. Cursor Settings → MCP or your project/user mcp.json), for example:

{
  "mcpServers": {
    "taboola-write": {
      "command": "npx",
      "args": ["-y", "@ideepakrajput/taboola-write-mcp"],
      "env": {
        "TABOOLA_CLIENT_ID": "your_client_id",
        "TABOOLA_CLIENT_SECRET": "your_client_secret",
        "DRY_RUN": "true"
      }
    }
  }
}

Alternatively run with node and a local build:

{
  "mcpServers": {
    "taboola-write": {
      "command": "node",
      "args": ["/absolute/path/to/taboola-write-mcp/dist/index.js"],
      "env": {
        "TABOOLA_CLIENT_ID": "your_client_id",
        "TABOOLA_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Claude Desktop

Edit Claude’s config file (location varies by OS; see Anthropic’s MCP docs) and add:

{
  "mcpServers": {
    "taboola-write": {
      "command": "npx",
      "args": ["-y", "@ideepakrajput/taboola-write-mcp"],
      "env": {
        "TABOOLA_CLIENT_ID": "your_client_id",
        "TABOOLA_CLIENT_SECRET": "your_client_secret",
        "DRY_RUN": "true"
      }
    }
  }
}

Restart Claude Desktop after saving.

Other MCP-capable apps

Use the same shape: command + args + env. If the app documents MCP servers, point it at npx -y @ideepakrajput/taboola-write-mcp or node /path/to/dist/index.js.

Capabilities (tools)

All tools are exposed to the LLM via MCP. Names match the server registration.

Campaigns

| Tool | Summary | |------|---------| | create_campaign | Create a campaign; tool uses bidding_strategy, API receives bid_strategy (defaults with cpc: FIXED + CPC); many accounts need spending_limit / spending_limit_model / tracking_code | | update_campaign | Partial campaign update | | duplicate_campaign | Duplicate with optional overrides | | bulk_update_campaigns | Bulk update up to 200 campaigns | | campaign_reach_estimator | Estimate monthly reach from targeting fields | | pause_campaign | Pause (inactive) | | activate_campaign | Activate | | stop_campaign | Deactivate (is_active=false) | | deactivate_campaign | Alias for deactivate | | set_campaign_budget | Budget settings | | set_campaign_bid | CPC bid |

Creatives & items

| Tool | Summary | |------|---------| | create_creative | Create creative in a campaign | | update_creative | Update creative by item id | | pause_creative | Pause creative item | | activate_creative | Activate creative item | | bulk_update_creatives | Bulk status updates | | mass_create_campaign_items | Mass create items for one campaign | | bulk_create_items_across_campaigns | Bulk create same items across campaigns |

Site lists & publishers

| Tool | Summary | |------|---------| | get_blocked_sites | Read blocked publisher sites for a campaign (GET campaign) | | block_sites | Append sites to campaign blocklist | | remove_blocked_sites | Remove sites from blocklist | | allowlist_sites | Allowlist-only serving | | block_publishers_account | Overwrite account-level suppressed publishers |

Targeting

| Tool | Summary | |------|---------| | set_geo_targeting | Country/geo targeting | | set_device_targeting | Platform targeting | | set_day_parting | Day-parting schedule | | update_postal_code_targeting | Postal code targeting | | update_my_audience_targeting | My audiences targeting | | update_marketplace_audience_targeting | Marketplace segments | | update_custom_audience_targeting | Custom audiences (include/exclude) | | update_lookalike_audience_targeting | Lookalike targeting | | update_contextual_segments_targeting | Contextual segments |

Audiences & pixel

| Tool | Summary | |------|---------| | create_first_party_audience | First-party audience create | | audience_onboarding_add_remove_users | Add/remove identities | | create_combined_audience | Combined audience (AND/OR/NOT) | | update_combined_audience | Update combined audience | | create_conversion_rule | Universal Pixel conversion rule | | update_conversion_rule | Update conversion rule | | create_custom_audience_rule | Pixel custom audience rule | | update_custom_audience_rule | Update custom audience rule |

Logs & data directory

• writes.jsonl: audit trail of tool inputs/results for successful writes.
• taboola-api-errors.jsonl: Taboola error responses (paths and hints may reference this file).

Default directory: ~/.cache/taboola-write-mcp (created automatically). Override with TABOOLA_MCP_DATA_DIR.

Operational notes

• Keep DRY_RUN=true until you trust prompts and tool behavior; then set false only in environments where writes are intended.
• Campaign and creative updates follow Taboola’s patterns (partial POST/PUT as implemented); avoid assuming silent merges—review payloads in dry-run mode first.
• API behavior depends on account type, permissions, and Taboola API versioning; failures may require checking the error log path returned by tools.

Development

npm install
npm run dev    # tsx src/index.ts
npm run build  # tsc → dist/
npm test       # vitest (if configured)

License

MIT — see package.json. This is an independent project (not affiliated with Taboola). Taboola is a trademark of its respective owner.