{"id":44382170,"url":"https://github.com/taboola/realize-mcp","last_synced_at":"2026-04-24T21:04:43.269Z","repository":{"id":301554919,"uuid":"1009591300","full_name":"taboola/realize-mcp","owner":"taboola","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-16T23:28:41.000Z","size":296,"stargazers_count":3,"open_issues_count":2,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-17T01:27:21.525Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/taboola.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-27T11:34:08.000Z","updated_at":"2026-04-12T04:30:57.000Z","dependencies_parsed_at":"2026-02-12T00:05:40.783Z","dependency_job_id":null,"html_url":"https://github.com/taboola/realize-mcp","commit_stats":null,"previous_names":["taboola/realize-mcp"],"tags_count":27,"template":false,"template_full_name":null,"purl":"pkg:github/taboola/realize-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taboola%2Frealize-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taboola%2Frealize-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taboola%2Frealize-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taboola%2Frealize-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/taboola","download_url":"https://codeload.github.com/taboola/realize-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/taboola%2Frealize-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32240614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-11T23:36:25.165Z","updated_at":"2026-04-24T21:04:43.262Z","avatar_url":"https://github.com/taboola.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Realize MCP Server\n\nA 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.\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Python](https://img.shields.io/badge/Python-3.10+-green.svg)](https://python.org) [![MCP](https://img.shields.io/badge/MCP-Compatible-orange.svg)](https://modelcontextprotocol.io/) [![Latest Version][mdversion-button]][md-pypi]\n\n[mdversion-button]: https://img.shields.io/pypi/v/realize-mcp.svg\n[md-pypi]: https://pypi.org/project/realize-mcp/\n\n---\n\n## Quick Start (Remote MCP)\n\nConnect to the hosted Realize MCP server using [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport with OAuth 2.1. Multi-user, stateless, no local install required.\n\n**Cursor IDE / Claude Desktop** — Add to your MCP client config:\n\n```json\n{\n  \"mcpServers\": {\n    \"realize-mcp\": {\n      \"url\": \"https://mcp.realize.com/mcp\"\n    }\n  }\n}\n```\n\n**Claude Desktop (UI)**\n\n1. Go to Settings → Connectors → Add Custom Connector\n2. Enter the MCP Server name and URL: `https://mcp.realize.com/mcp`\n3. Select **Connect** to initiate the OAuth 2.1 flow\n4. A browser window will open to Taboola SSO—enter your credentials to obtain a bearer token used by Realize tools\n\n**Claude Code (CLI)**\n\n```bash\nclaude mcp add --transport http --callback-port 3000 realize-mcp https://mcp.realize.com/mcp\n```\n\n---\n\n## Tools Reference\n\n### Account Management\n\n**`search_accounts`** — Search accounts by numeric ID or text query. **Call this first** to get `account_id` values needed by all other tools.\n\n```\nquery       (string, required)            Cannot be empty. Numeric = exact ID; text = fuzzy name\npage        (integer, default: 1)         min: 1\npage_size   (integer, default: 10)        min: 1, max: 10 (hard cap)\n```\n\n### Campaign Management\n\nAll campaign tools require `account_id` (string from `search_accounts`), not a raw numeric ID.\nNo pagination — all results returned in a single response.\n\n**`get_all_campaigns`** — List all campaigns for an account.\n\n```\naccount_id  (string, required)\n```\n\n**`get_campaign`** — Get specific campaign details.\n\n```\naccount_id  (string, required)\ncampaign_id (string, required)\n```\n\n**`get_campaign_items`** — Get all items/creatives for a campaign.\n\n```\naccount_id  (string, required)\ncampaign_id (string, required)\n```\n\n**`get_campaign_item`** — Get a specific campaign item's details.\n\n```\naccount_id  (string, required)\ncampaign_id (string, required)\nitem_id     (string, required)\n```\n\n### Reporting (CSV Format)\n\nAll report tools return CSV with a summary header. Every report requires these parameters:\n\n```\naccount_id  (string, required)            From search_accounts\nstart_date  (string, required)            Format: YYYY-MM-DD\nend_date    (string, required)            Format: YYYY-MM-DD\npage        (integer, default: 1)         min: 1\npage_size   (integer, default: 20)        min: 1, max: 100\n```\n\nSome reports also support sorting and filtering:\n\n```\nsort_field      (string, optional)        Allowed: clicks, spent, impressions\nsort_direction  (string, default: DESC)   Allowed: ASC, DESC\nfilters         (object, optional)        JSON object with string values only\n```\n\n**`get_top_campaign_content_report`** — Top performing campaign content.\nSupports: shared params + sort.\n\n**`get_campaign_breakdown_report`** — Campaign performance breakdown.\nSupports: shared params + sort + filters.\n\n**`get_campaign_history_report`** — Historical campaign data.\nSupports: shared params only (no sort, no filters).\n\n**`get_campaign_site_day_breakdown_report`** — Site/day performance breakdown.\nSupports: shared params + sort + filters.\n\n### Authentication (stdio only)\n\nThese 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.\n\n**`get_auth_token`** — Authenticate with Realize API using client credentials (`REALIZE_CLIENT_ID`/`REALIZE_CLIENT_SECRET`).\n\n**`get_token_details`** — Get details about the current authentication token.\n\n---\n\n## Usage Examples\n\n### Basic Usage\n\n```\nUser: \"Show me campaigns for Marketing Corp\"\nAI:\n  1. Searches accounts for \"Marketing Corp\"\n  2. Retrieves campaigns using the found account_id\n  3. Returns campaign list with performance metrics\n```\n\n**Important**: All operations require getting `account_id` values from `search_accounts` first - never use numeric IDs directly.\n\n### Find Account and List Campaigns\n\n```\nUser: \"Show campaigns for account 12345\"\nAI Process:\n  Step 1: search_accounts(\"12345\") → Returns account_id: \"advertiser_12345_prod\"\n  Step 2: get_all_campaigns(account_id=\"advertiser_12345_prod\")\n  Result: List of campaigns with details\n```\n\n### Get Performance Report\n\n```\nUser: \"Get campaign performance for Marketing Corp last month\"\nAI Process:\n  Step 1: search_accounts(\"Marketing Corp\") → account_id: \"mktg_corp_001\"\n  Step 2: get_campaign_breakdown_report(\n    account_id=\"mktg_corp_001\",\n    start_date=\"2024-01-01\",\n    end_date=\"2024-01-31\"\n  )\n  Result: CSV report with campaign metrics\n```\n\n### Top Performing Content\n\n```\nUser: \"Show top 20 performing content items\"\nAI Process:\n  get_top_campaign_content_report(\n    account_id=\"account_id_from_search\",\n    start_date=\"2024-01-01\",\n    end_date=\"2024-01-31\",\n    page_size=20,\n    sort_field=\"spent\",\n    sort_direction=\"DESC\"\n  )\n  Result: Top content sorted by spend\n```\n\n### Report Features\n\n- **CSV Format**: Reports return efficient CSV data with headers and pagination info\n- **Pagination**: Default page_size=20, max=100 to prevent overwhelming responses\n- **Sorting**: Available for most reports by `clicks`, `spent`, or `impressions`\n- **Size Optimization**: Automatic truncation for large datasets\n\n---\n\n## Prometheus Metrics\n\nEnabled by default (`METRICS_ENABLED=true`). Served on a dedicated port (default `8092`, configurable via `METRICS_PORT`) in Streamable HTTP mode.\n\n| Metric | Type | Labels |\n|--------|------|--------|\n| `realize_mcp_http_requests_total` | Counter | `method`, `endpoint`, `http_status` |\n| `realize_mcp_http_request_latency_seconds` | Histogram | `endpoint` |\n| `realize_mcp_tool_calls_total` | Counter | `tool_name`, `status` |\n| `realize_mcp_tool_call_latency_seconds` | Histogram | `tool_name` |\n| `realize_mcp_client_connections_total` | Counter | `client_name`, `client_version` |\n| `realize_mcp_api_requests_total` | Counter | `method`, `endpoint_pattern`, `http_status` |\n| `realize_mcp_api_request_latency_seconds` | Histogram | `method`, `endpoint_pattern` |\n| `realize_mcp_api_errors_total` | Counter | `method`, `endpoint_pattern`, `error_type` |\n\n---\n\n## Local Setup\n\nRun the MCP server locally if you prefer to manage your own credentials or host the server yourself.\n\n### Prerequisites\n\n- Python 3.10+ (Python 3.11+ recommended)\n- MCP-compatible client (Claude Desktop, Cursor, VS Code, etc.)\n\n### Option A: Stdio Transport (single-user, local)\n\nStandard MCP transport for local clients. The server runs on your machine and uses server-side credentials for Taboola API authentication.\n\n**Prerequisites:** Taboola Realize API credentials (`REALIZE_CLIENT_ID` and `REALIZE_CLIENT_SECRET`)\n\n**Install:**\n\n```bash\npip install realize-mcp\n```\n\n**Cursor IDE** - Add to Settings → Tools \u0026 MCP:\n\n```json\n{\n  \"mcpServers\": {\n    \"realize-mcp\": {\n      \"command\": \"realize-mcp-server\",\n      \"env\": {\n        \"REALIZE_CLIENT_ID\": \"your_client_id\",\n        \"REALIZE_CLIENT_SECRET\": \"your_client_secret\"\n      }\n    }\n  }\n}\n```\n\n**Claude Desktop** - Add to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"realize-mcp\": {\n      \"command\": \"realize-mcp-server\",\n      \"env\": {\n        \"REALIZE_CLIENT_ID\": \"your_client_id\",\n        \"REALIZE_CLIENT_SECRET\": \"your_client_secret\"\n      }\n    }\n  }\n}\n```\n\n**Claude Code (CLI)**\n\n```bash\nclaude mcp add realize-mcp --transport stdio -e REALIZE_CLIENT_ID=your_client_id -e REALIZE_CLIENT_SECRET=your_client_secret -- realize-mcp-server\n```\n\n### Option B: Self-Hosted Streamable HTTP\n\nRun the Streamable HTTP transport yourself (multi-user via OAuth 2.1, stateless, k8s-friendly).\n\n**Prerequisites:**\n- OAuth Dynamic Client Registration client ID (`OAUTH_DCR_CLIENT_ID`)\n- Optional: `OAUTH_SERVER_URL` (defaults to `https://authentication.taboola.com/authentication`)\n- Publicly accessible server URL for OAuth callbacks\n- `MCP_SERVER_SCHEME` — defaults to `https`. Set to `http` for local dev without TLS.\n\n**Install:**\n\n```bash\npip install realize-mcp\n```\n\n**Start the server:**\n\n```bash\nMCP_TRANSPORT=streamable-http OAUTH_DCR_CLIENT_ID=your_dcr_client_id realize-mcp-server\n```\n\n**Client config** (point to your self-hosted URL):\n\n```json\n{\n  \"mcpServers\": {\n    \"realize-mcp\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://your-mcp-server.example.com/mcp\"\n    }\n  }\n}\n```\n\n**Endpoints:**\n\n- `GET /.well-known/oauth-protected-resource` - RFC 9728 Protected Resource Metadata (supports path-based discovery)\n- `GET /.well-known/oauth-authorization-server` - RFC 8414 metadata (registration_endpoint rewritten)\n- `POST /register` - RFC 7591 Dynamic Client Registration\n- `POST|GET|DELETE /mcp` - MCP Streamable HTTP endpoint (requires Bearer token)\n- `GET /health` - Health check endpoint for Kubernetes probes\n- `GET /` on port 8092 - Prometheus metrics endpoint (separate port)\n\n### Troubleshooting\n\nTest the server manually:\n\n```bash\nREALIZE_CLIENT_ID=test REALIZE_CLIENT_SECRET=test realize-mcp-server\n```\n\nYou should see: `INFO:realize.realize_server:Starting Realize MCP Server...`\n\n---\n\n## Detailed Documentation\n\nFor comprehensive information, see [design.md](design.md):\n\n- **Recent Fixes \u0026 Version History** - Detailed release notes and upgrade instructions\n- **Installation Options** - PyPI \u0026 Source installation with troubleshooting\n- **Architecture \u0026 Design Principles** - Technical implementation details\n- **Advanced Features** - CSV format, pagination, sorting, and optimization\n- **Development Guide \u0026 Testing** - Setup, testing, and contribution guidelines\n- **Comprehensive Troubleshooting** - Detailed solutions for common issues\n- **Security Best Practices** - Credential management and operational security\n- **Complete API Reference** - Full technical API documentation\n- **Technology Stack Details** - Dependencies and system requirements\n\n---\n\n## License\n\nLicensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.\n\n---\n\n**Realize MCP Server** - Safe, efficient, access to Taboola's advertising platform through natural language.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaboola%2Frealize-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftaboola%2Frealize-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftaboola%2Frealize-mcp/lists"}