Taboola_mcp

Taboola MCP Connector

An MCP (Model Context Protocol) tool that connects Taboola Advertising API with AI assistants like Claude (in Cursor, Claude Desktop, etc.), allowing you to analyze your campaign data through natural language conversations.

Features

Natural Language Querying: Ask questions about your Taboola campaigns in plain English
Campaign Performance Analysis: Get summaries, trends, and insights about your advertising performance
Account Management: View all your accounts and campaigns in one place
Data Visualization: See performance trends with simple ASCII charts right in your chat interface
Comprehensive Insights: Get actionable recommendations based on your campaign data

Setup

Prerequisites

Python 3.8+ installed
A Taboola account with API access
Valid Taboola API credentials (client ID and client secret)

Installation

Clone or download this repository and install dependencies
Install dependencies
```
pip install -r requirements.txt
```
Set up your environment variables

Create a .env file in the root directory with your Taboola API credentials:
```
TABOOLA_CLIENT_ID=your_client_id
TABOOLA_CLIENT_SECRET=your_client_secret
```
Test the connector

Run the script to verify it connects to Taboola correctly:
```
python taboola_connector.py
```
You should see logs indicating successful authentication and account loading.

Using with Cursor

Add the connector to Cursor’s MCP configuration

Open or create .cursor/mcp.json in your user directory and add the following entry:

{
  "mcpServers": {
    "Taboola_Connector": {
      "command": "FULL/PATH/TO/YOUR/DIRECTORY/taboola_mcp/.venv/Scripts/python",
      "args": [
        "FULL/PATH/TO/YOUR/DIRECTORY/taboola_mcp/taboola_connector.py"
      ]
    }
  }
}

Restart Cursor

Close and reopen Cursor to load the updated MCP configuration.
Verify the connection

In Cursor’s chat, ask a simple question like “List my Taboola accounts” to verify the connection works.

Available Tools

The connector provides the following tools for interacting with Taboola:

Tool Name	Description	Example Query
`list_taboola_accounts`	Lists all accessible Taboola accounts	“Show me all my Taboola accounts”
`taboola_account_overview`	Provides a comprehensive account overview	“Give me an overview of account wattfoxgmbh-network”
`get_taboola_account_currency`	Retrieves the account’s currency code	“What currency is my Taboola account using?”
`list_taboola_campaigns`	Lists all campaigns in an account	“List all campaigns in my wattfoxgmbh-network account”
`get_taboola_campaign_summary`	Gets performance summary for campaigns	“Summarize campaign performance for April”
`get_taboola_campaign_details`	Gets detailed info about a specific campaign	“Show me details for campaign 44471496”
`analyze_taboola_performance`	Analyzes campaign performance with detailed metrics	“Analyze my campaign performance from April 1 to April 23”
`get_taboola_creatives`	Lists all creative assets in an account	“Show me all creatives in my Taboola account”
`get_taboola_creative_details`	Gets detailed info about a specific creative	“Show details for creative asset 123456”
`analyze_taboola_creative_performance`	Analyzes creative performance with metrics	“Which creatives performed best last month?”
`get_taboola_ads`	Lists all ads or ads for a specific campaign	“Show me all ads in campaign 44471496”
`download_taboola_creative`	Downloads a creative asset from its URL	“Download the creative at https://example.com/image.jpg”

Example Queries

You can ask questions in natural language like:

“Show me my Taboola campaign performance for the last 30 days.”
“What were my top performing campaigns last month?”
“List all my active Taboola campaigns.”
“Give me a summary of my account performance with charts.”
“Analyze my campaign data from June 1 to June 30.”
“Which campaigns had the highest CTR last week?”

Troubleshooting

Connection Issues

“TaboolaConnector is not available”: Check that your .env file exists with correct credentials.
Python Command Not Found: Make sure the Python path in .cursor/mcp.json is correctly specified.
No tools available: Ensure the MCP server is running correctly by checking logs in taboola_mcp.log.

Authentication Errors

Bad client credentials: Verify your TABOOLA_CLIENT_ID and TABOOLA_CLIENT_SECRET are correct.
No accounts found: Check that your API credentials have access to the accounts you’re trying to query.

Path Issues

If you see errors about files not found, make sure all paths in your configuration are absolute paths (not relative).

Technical Details

The connector communicates with the Taboola API to retrieve campaign data, and exposes this data through MCP tools. This allows AI assistants to query and analyze your advertising data.

The connector follows these steps: