# 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.
[](https://opensource.org/licenses/Apache-2.0)
[](https://python.org)
[](https://modelcontextprotocol.io/)
## Quick Start
### Cursor IDE Setup
Add to Cursor Settings → Features → Model Context Protocol:
```json
{
"mcpServers": {
"realize-mcp": {
"command": "realize-mcp-server",
"env": {
"REALIZE_CLIENT_ID": "your_client_id",
"REALIZE_CLIENT_SECRET": "your_client_secret"
}
}
}
}
```
### Claude Desktop Setup
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"realize-mcp": {
"command": "realize-mcp-server",
"env": {
"REALIZE_CLIENT_ID": "your_client_id",
"REALIZE_CLIENT_SECRET": "your_client_secret"
}
}
}
}
```
### Installation
```bash
pip install realize-mcp
```
### Setup
```bash
# Set credentials
export REALIZE_CLIENT_ID="your_client_id"
export REALIZE_CLIENT_SECRET="your_client_secret"
```
## 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.
## Available Tools
### 🔍 Account Management
- `search_accounts` - **[REQUIRED FIRST]** Find accounts and get account_id values for other tools (with pagination support: page_size max 10)
### 📊 Campaign Tools
- `get_all_campaigns` - List all campaigns for an account
- `get_campaign` - Get detailed campaign information
- `get_campaign_items` - List campaign creative items
- `get_campaign_item` - Get specific item details
### 📈 Reporting Tools (CSV Format)
- `get_top_campaign_content_report` - Top performing content with sorting & pagination
- `get_campaign_breakdown_report` - Campaign performance breakdown with sorting & pagination
- `get_campaign_history_report` - Historical campaign data with pagination
- `get_campaign_site_day_breakdown_report` - Site/day performance breakdown with sorting & pagination
### 🔐 Authentication
- `get_auth_token` - Authenticate with Realize API
- `get_token_details` - Check token information
## Prerequisites
- **Python 3.10+** (Python 3.11+ recommended)
- **Taboola Realize API credentials** (client ID and secret)
- **MCP-compatible client** (Claude Desktop, Cursor, VS Code, etc.)
## Usage Examples
### 1. 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
```
### 2. 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
```
### 3. 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
```
## 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
## Quick Troubleshooting
If you encounter issues with the MCP server, try this quick diagnostic:
```bash
# Test 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](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](LICENSE) for details.
---
**Realize MCP Server** - Safe, efficient, read-only access to Taboola's advertising platform through natural language.
Raw data
{
"_id": null,
"home_page": null,
"name": "realize-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, taboola, realize, advertising, campaigns, ai",
"author": null,
"author_email": "Vladi Manaev <vladi.m@taboola.com>",
"download_url": "https://files.pythonhosted.org/packages/d1/37/915012c6a9163b86c544bccbc6792e764b03ac3e8425b50fa539f113bf57/realize_mcp-1.0.5.tar.gz",
"platform": null,
"description": "# 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.\n\n[](https://opensource.org/licenses/Apache-2.0)\n[](https://python.org)\n[](https://modelcontextprotocol.io/)\n\n## Quick Start\n\n### Cursor IDE Setup\n\nAdd to Cursor Settings \u2192 Features \u2192 Model Context Protocol:\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 Setup\n\nAdd to your `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### Installation\n\n```bash\npip install realize-mcp\n```\n\n### Setup\n\n```bash\n# Set credentials\nexport REALIZE_CLIENT_ID=\"your_client_id\"\nexport REALIZE_CLIENT_SECRET=\"your_client_secret\"\n```\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## Available Tools\n\n### \ud83d\udd0d Account Management\n- `search_accounts` - **[REQUIRED FIRST]** Find accounts and get account_id values for other tools (with pagination support: page_size max 10)\n\n### \ud83d\udcca Campaign Tools \n- `get_all_campaigns` - List all campaigns for an account\n- `get_campaign` - Get detailed campaign information\n- `get_campaign_items` - List campaign creative items\n- `get_campaign_item` - Get specific item details\n\n### \ud83d\udcc8 Reporting Tools (CSV Format)\n- `get_top_campaign_content_report` - Top performing content with sorting & pagination\n- `get_campaign_breakdown_report` - Campaign performance breakdown with sorting & pagination \n- `get_campaign_history_report` - Historical campaign data with pagination\n- `get_campaign_site_day_breakdown_report` - Site/day performance breakdown with sorting & pagination\n\n### \ud83d\udd10 Authentication\n- `get_auth_token` - Authenticate with Realize API\n- `get_token_details` - Check token information\n\n## Prerequisites\n\n- **Python 3.10+** (Python 3.11+ recommended)\n- **Taboola Realize API credentials** (client ID and secret)\n- **MCP-compatible client** (Claude Desktop, Cursor, VS Code, etc.)\n\n## Usage Examples\n\n### 1. Find Account and List Campaigns\n```\nUser: \"Show campaigns for account 12345\"\nAI Process:\n Step 1: search_accounts(\"12345\") \u2192 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### 2. Get Performance Report\n```\nUser: \"Get campaign performance for Marketing Corp last month\"\nAI Process:\n Step 1: search_accounts(\"Marketing Corp\") \u2192 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### 3. Top Performing Content\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## Important Workflow Notes\n\n### \u26a0\ufe0f Account ID Requirement\n\n**All campaign and report tools require `account_id` values from `search_accounts`:**\n\n\u2705 **Correct Workflow:**\n```\n1. search_accounts(\"company name\" or \"numeric_id\") \n2. Extract account_id from response\n3. Use account_id in other tools\n```\n\n\u274c **Incorrect:**\n```\nget_all_campaigns(account_id=\"12345\") # Numeric IDs won't work\n```\n\n### \ud83d\udcca 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## Quick Troubleshooting\n\nIf you encounter issues with the MCP server, try this quick diagnostic:\n\n```bash\n# Test server manually\nREALIZE_CLIENT_ID=test REALIZE_CLIENT_SECRET=test realize-mcp-server\n```\nYou should see: `INFO:realize.realize_server:Starting Realize MCP Server...`\n\n## Detailed Documentation\n\n\ud83d\udcd6 **For comprehensive information, see [design.md](design.md):**\n\n- **Recent Fixes & Version History** - Detailed release notes and upgrade instructions\n- **Installation Options** - PyPI & Source installation with troubleshooting \n- **Architecture & Design Principles** - Technical implementation details\n- **Advanced Features** - CSV format, pagination, sorting, and optimization\n- **Development Guide & 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## License\n\nLicensed under the Apache License 2.0. See [LICENSE](LICENSE) for details.\n\n---\n\n**Realize MCP Server** - Safe, efficient, read-only access to Taboola's advertising platform through natural language. \n",
"bugtrack_url": null,
"license": null,
"summary": "MCP server for Taboola's Realize API - campaign analysis and reporting",
"version": "1.0.5",
"project_urls": {
"Bug Tracker": "https://github.com/taboola/realize-mcp/issues",
"Documentation": "https://github.com/taboola/realize-mcp#readme",
"Homepage": "https://github.com/taboola/realize-mcp",
"Repository": "https://github.com/taboola/realize-mcp"
},
"split_keywords": [
"mcp",
" taboola",
" realize",
" advertising",
" campaigns",
" ai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "c6bbd84b709fd89f3c71fbb7b6eaea00396741e010c4d12867d09499d6080428",
"md5": "efd92c2e6c4ae49e4a09b60173a51fd7",
"sha256": "da549719717b7608fe7e3dbf25e2f4826458a5b515debb113b6cc579b5c05530"
},
"downloads": -1,
"filename": "realize_mcp-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "efd92c2e6c4ae49e4a09b60173a51fd7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 24041,
"upload_time": "2025-07-18T20:51:05",
"upload_time_iso_8601": "2025-07-18T20:51:05.614292Z",
"url": "https://files.pythonhosted.org/packages/c6/bb/d84b709fd89f3c71fbb7b6eaea00396741e010c4d12867d09499d6080428/realize_mcp-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d137915012c6a9163b86c544bccbc6792e764b03ac3e8425b50fa539f113bf57",
"md5": "887483415a5daf0a7562d12e7cf096aa",
"sha256": "e063773334fe0aec54dd295ec5b76feaa797f3298a1150b3693b2f858830f5e2"
},
"downloads": -1,
"filename": "realize_mcp-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "887483415a5daf0a7562d12e7cf096aa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 37908,
"upload_time": "2025-07-18T20:51:06",
"upload_time_iso_8601": "2025-07-18T20:51:06.865028Z",
"url": "https://files.pythonhosted.org/packages/d1/37/915012c6a9163b86c544bccbc6792e764b03ac3e8425b50fa539f113bf57/realize_mcp-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-18 20:51:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "taboola",
"github_project": "realize-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.31.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.25.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.8.0"
]
]
},
{
"name": "pytest",
"specs": [
[
">=",
"7.4.0"
]
]
},
{
"name": "pytest-asyncio",
"specs": [
[
">=",
"0.21.0"
]
]
},
{
"name": "build",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "twine",
"specs": [
[
">=",
"6.0.0"
]
]
},
{
"name": "setuptools",
"specs": [
[
">=",
"61.0"
]
]
},
{
"name": "wheel",
"specs": [
[
">=",
"0.40.0"
]
]
}
],
"lcname": "realize-mcp"
}
JSON
