Which integrations are available for this server?

Enables searching the Facebook (Meta) Ads Library by keyword or brand name, retrieving live ad copy, impressions, and platform details. Enables searching the Google Ads Transparency Center to retrieve live ad copy, days active, formats, and regions across Search, Display, YouTube, and Shopping ads. Enables fetching public Instagram profile data including follower counts, bio, and recent posts.

All About Ads MCP

by rugvedp

Overview Schema Related Servers Score Discussions

Python

Remote

all-about-ads-mcp

An MCP (Model Context Protocol) server that gives AI agents live, structured ad intelligence across Facebook, Google, and Instagram — data that no base model can produce from training alone.

Demo

Related MCP server: google-ads-transparency-mcp

Why this MCP exists

A base AI model can tell you what lululemon's general marketing strategy looks like — based on articles it was trained on, months ago. It cannot tell you:

What ad copy is running right now on Facebook or Google
Whether a competitor started or stopped a campaign last week
Which countries a brand is targeting today
How long a specific ad has been active (days_active)

This MCP fetches live truth, not remembered facts.

Capability	Base AI	This MCP + AI
Brand's current ad copy	Guesses from old training	Live, exact headlines
Ad volume for analysis	1–3 examples at best	10–100+ per run
Cross-platform in one session	Impossible	FB + Google + IG + SERP
Time an ad has been running	Unknown	Exact (`days_active` field)
New market ad landscape	Outdated	Real-time, filterable by country
Verify if brand is advertising	Assumption	Confirmed fact
Research speed	One query at a time	Tools run in parallel — hundreds of ads across platforms in minutes

Platform coverage

Platform coverage diagram

How results are handled

Tools run in parallel — an AI agent can fire off Facebook, Google, and Instagram scrapers simultaneously rather than waiting for each one to finish before starting the next. That's why a full multi-platform research session completes in minutes, not hours.

Scraper runs take 30 seconds to a few minutes. Raw payloads can be enormous, so the architecture keeps the AI's context window safe:

Results handling diagram

Full results are never sent to the model in one shot. The preview gives enough signal; read_saved_results provides paginated, filterable access to the rest.

Use cases

1. Competitive intelligence before a pitch

An agency pitching a new client can build a full picture in minutes instead of days:

Competitive intelligence diagram

No base AI can give you what's actually running today across all three platforms simultaneously.

2. Evergreen ad detection

The days_active field in Google Ads shows exactly how long each creative has been live. An ad running for 1,000+ days is a proven, high-converting asset. Use this to find what competitors refuse to turn off:

Evergreen ad detection diagram

3. Market entry gap analysis

Before entering a new market, check who's already advertising there:

Market entry gap analysis diagram

A base AI would guess based on 2023 data. This gives real-time confirmation.

4. PR crisis correlation

When a brand faces a scandal, do they pull ads or keep running? Track it in real time:

PR crisis correlation diagram

5. Ad creative pattern analysis at scale

Pull 100 ads from a fast-growing brand and let the AI find the formula:

Ad creative pattern analysis diagram

This requires structured bulk data to reason over — not 3 examples recalled from training.

6. Political ad transparency

Track political advertising by region with verifiable, primary-source data:

Political ad transparency diagram

7. Full brand research loop

The complete workflow an AI agent can run autonomously:

Project layout

all-about-ads-mcp/
├── src/
│   ├── server.py      # FastMCP server instance
│   ├── tools.py       # 6 MCP tool definitions
│   ├── storage.py     # Result persistence + per-platform summarisers
│   └── resources.py   # ads://about resource
├── main.py            # Entry point (stdio transport)
├── pyproject.toml
└── uv.lock

Setup

1. Install dependencies:

uv sync

2. Configure your Apify API token:

cp .env.example .env
# edit .env and set APIFY_API_TOKEN=<your token>

Get a free token at apify.com — the free tier covers light research use.

Connecting MCP clients

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "all-about-ads": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/all-about-ads-mcp", "main.py"],
      "env": {
        "APIFY_API_TOKEN": "your_apify_token_here"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "all-about-ads": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/all-about-ads-mcp", "main.py"],
      "env": {
        "APIFY_API_TOKEN": "your_apify_token_here"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "all-about-ads": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/all-about-ads-mcp", "main.py"],
      "env": {
        "APIFY_API_TOKEN": "your_apify_token_here"
      }
    }
  }
}

VS Code (with GitHub Copilot)

Add to your .vscode/mcp.json in the workspace root:

{
  "servers": {
    "all-about-ads": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/all-about-ads-mcp", "main.py"],
      "env": {
        "APIFY_API_TOKEN": "your_apify_token_here"
      }
    }
  }
}

Docker (any client)

If you prefer not to install Python/uv locally, run the pre-built container. The container communicates over stdio just like the native install:

Build the image:

docker build -t all-about-ads-mcp .

Claude Desktop / Cursor / Windsurf config:

{
  "mcpServers": {
    "all-about-ads": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "APIFY_API_TOKEN", "all-about-ads-mcp"],
      "env": {
        "APIFY_API_TOKEN": "your_apify_token_here"
      }
    }
  }
}

-i is required (stdin must stay open for stdio transport). Do not use -t (no TTY needed).

Publishing to MCP directories

Smithery

Smithery reads the smithery.yaml in this repo automatically. To publish:

Push this repo to GitHub
Go to smithery.ai → Submit a server → paste your GitHub URL
Smithery reads smithery.yaml and handles deployment — users configure their APIFY_API_TOKEN in the Smithery UI

Glama

Glama indexes public GitHub repos. To publish:

Push this repo to GitHub (public)
Go to glama.ai/mcp/servers → Add Server → paste your GitHub URL

mcpservers.org

mcpservers.org is a community directory. To submit:

Push to GitHub
Go to mcpservers.org/submit and fill in the form

Tools

`search_facebook_ads`

Search the Facebook (Meta) Ads Library by keyword or brand name.

Parameter	Type	Default	Description
`search_queries`	`list[str]`	required	Keywords or brand names
`max_results_per_query`	`int`	`10`	Min 10 (actor limit)
`enrich_with_ad_details`	`bool`	`false`	Extra per-ad details (slower)
`sort_by`	`str`	`SORT_BY_TOTAL_IMPRESSIONS`	Or `SORT_BY_RELEVANCY_MONTHLY_GROUPED`
`country`	`str \| null`	`null`	ISO code e.g. `"US"`, `"IN"`, or `"ALL"`
`content_languages`	`list[str] \| null`	`null`	e.g. `["en"]`
`publisher_platforms`	`list[str] \| null`	`null`	e.g. `["facebook", "instagram"]`
`active_status`	`str`	`ALL`	`ALL`, `ACTIVE`, `INACTIVE`
`ad_type`	`str`	`ALL`	`ALL`, `POLITICAL_AND_ISSUE_ADS`, `HOUSING_ADS`, `EMPLOYMENT_ADS`, `CREDIT_ADS`
`media_type`	`str`	`ALL`	`ALL`, `IMAGE`, `MEME`, `VIDEO`, `NONE`
`start_date` / `end_date`	`str \| null`	`null`	`YYYY-MM-DD`

Returns: file_path, result_count, queries, ads (compact preview)

`search_google_ads`

Search the Google Ads Transparency Center — covers Search, Display, YouTube, and Shopping ads.

Parameter	Type	Default	Description
`advertisers`	`list[str]`	required	Brand names, domains (`"nike.com"`), full URLs, or advertiser IDs (`"AR..."`)
`max_ads_per_advertiser`	`int`	`100`	`0` = unlimited
`start_date` / `end_date`	`str \| null`	`null`	`YYYY-MM-DD`
`region`	`str \| null`	`null`	2-letter ISO code e.g. `"US"`, `"GB"`
`political_ads_only`	`bool`	`false`	Restrict to political/election ads

Returns: file_path, result_count, advertisers, ads (compact preview with days_active, headline, format, regions, destination_url)

`search_instagram_profiles`

Fetch public Instagram profile data including follower counts, bio, and recent posts.

Parameter	Type	Default	Description
`profiles`	`list[str]`	required	Instagram usernames e.g. `["natgeo", "nike"]`
`include_recent_posts`	`bool`	`true`	Also fetch recent posts

Returns: file_path, result_count, profiles (compact preview with followers, bio, verified status)

`search_google`

Search Google for organic results — use for brand research, news, and context about ads you've discovered.

Parameter	Type	Default	Description
`queries`	`list[str]`	required	Search queries
`max_pages_per_query`	`int`	`1`	Each page ≈ 10 results
`results_per_page`	`int`	`10`	Range: 10–100
`country_code`	`str \| null`	`null`	e.g. `"gb"` → google.co.uk
`search_language`	`str \| null`	`null`	e.g. `"en"`, `"fr"`
`quick_date_range`	`str \| null`	`null`	`d10`, `w2`, `m6`, `y1`

Returns: file_path, result_count (individual URLs), queries, results (compact preview)

`list_saved_results`

List all previously saved result files with path, size, item count, tool name, and queries. No Apify call — instant.

`read_saved_results`

Read a slice of items from a saved file — fast access without re-running scrapers.

Parameter	Type	Default	Description
`file_path`	`str`	required	Path or bare filename from `list_saved_results`
`offset`	`int`	`0`	First item index
`limit`	`int`	`5`	Max items to return
`fields`	`list[str] \| null`	`null`	Project only these top-level keys
`query`	`str \| null`	`null`	Case-insensitive substring filter across item JSON

Resources

ads://about — full parameter reference for all tools, readable by the AI agent at session start.

Available Tools

11 tools

check_run_statusA

Read-only

Check the current status of one or more background Apify scrape runs.

Returns done and succeeded flags for each run so you know when to call collect_scrape_results.

ParametersJSON Schema

Name	Required	Description	Default
`run_ids`	Yes	Run IDs returned by start_facebook_ads_scrape, start_google_ads_scrape, or start_instagram_scrape.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true so the description adds value by specifying return flags and the follow-up action. There is no contradiction, and the description is consistent with the read-only nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first states purpose, second explains return value and follow-up. Every sentence is necessary and front-loaded with the core action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the tool's purpose, return values, and usage hint. With an output schema present, it does not need to detail return structure. It is complete for the given complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter run_ids has a description in the schema that is identical to what the tool description mentions. Schema coverage is 100%, so the description does not add new meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Check the current status of one or more background Apify scrape runs' with specific verb and resource. It distinguishes from sibling tools like collect_scrape_results by noting the return of done/succeeded flags.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description indicates the tool is for checking background runs and signals when to use sibling tool collect_scrape_results. It does not explicitly state when not to use it or list alternatives, but the context is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

collect_scrape_resultsA

Collect and save results from a completed background Apify scrape run.

The run must have SUCCEEDED — check with check_run_status first. Results are saved to a file and a compact preview is returned inline, identical to the blocking search_* tools.

ParametersJSON Schema

Name	Required	Description	Default
`run_id`	Yes	Run ID returned by start_facebook_ads_scrape, start_google_ads_scrape, or start_instagram_scrape.

Output Schema

ParametersJSON Schema

Name	Required	Description
`meta`	Yes
`items`	Yes
`offset`	Yes
`returned`	Yes
`total_items`	Yes
`matched_items`	Yes

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that results are saved to a file and a compact preview is returned, identical to search_* tools. Annotations indicate non-read-only and side effects, but description adds meaningful context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences front-loaded with verb+resource, then precondition. No wasted words; structure aids quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, prerequisite, behavioral detail (saving, preview), and output comparison. Simple tool with output schema; description is fully adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only parameter 'run_id' is documented in schema with clear description. Schema coverage is 100%, so baseline 3 applies; description does not add beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states 'Collect and save results from a completed background Apify scrape run.' Differentiates from siblings like start_* (initiate) and check_run_status (monitor status).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'The run must have SUCCEEDED — check with check_run_status first.' Provides clear precondition and alternative approach.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_saved_resultsA

Read-only

List all result files saved from previous scraper runs.

Returns one entry per file with path, size, item count, tool name, and queries. No Apify call is made — this is instant. Use read_saved_results to read items.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true; the description adds that no Apify call is made and it's instant, providing useful behavioral context beyond annotations. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is three sentences, front-loaded with action, returns info, and a sibling reference. Every sentence is essential with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no parameters and an output schema existing, the description fully covers the tool's purpose, return values, and relationship to sibling, leaving no gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so no additional explanation needed. Baseline score of 4 for zero-parameter tools is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists result files from previous scraper runs, specifying what each entry contains (path, size, item count, tool name, queries) and differentiates from read_saved_results.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly directs users to use read_saved_results to read items and mentions that no Apify call is made (instant), indicating when to use this tool. Could be more explicit about when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_saved_resultsA

Read-only

Read a paginated slice of items from a previously saved scraper results file.

Results files can be very large. Read in small pages and project only the fields you need to stay within context limits.

ParametersJSON Schema

Name	Required	Description
`limit`	No	Maximum number of items to return per call.
`query`	No	Case-insensitive substring filter. Only items whose JSON contains this string are returned.
`fields`	No	If set, only these top-level keys are included per item. Use to reduce token usage.
`offset`	No	Index of the first item to return. Use with limit to paginate.
`file_path`	Yes	Path returned by a search tool or list_saved_results. A bare filename also works.

Output Schema

ParametersJSON Schema

Name	Required	Description
`meta`	Yes
`items`	Yes
`offset`	Yes
`returned`	Yes
`total_items`	Yes
`matched_items`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=false. The description adds context about large result files and recommends pagination and projection to stay within context limits. No contradictions; it complements the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise (three sentences) and front-loaded: the first sentence states the purpose, followed by two sentences of guidance. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (5 parameters, output schema exists), the description covers what the tool does, why it's important (large files), and how to use it (pagination, projection). It is complete for agent selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by explaining why to use parameters like 'limit' and 'fields' ('read in small pages and project only the fields you need'), reinforcing the purpose beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Read a paginated slice of items from a previously saved scraper results file.' It uses a specific verb ('Read') and resource ('paginated slice of items') and differentiates from siblings like 'list_saved_results' and 'collect_scrape_results' by focusing on pagination and projection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear guidance: 'Read in small pages and project only the fields you need to stay within context limits.' This helps the agent understand when to use pagination and projection. However, it does not explicitly state when not to use this tool or suggest alternatives for cases like retrieving all items at once.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_facebook_adsA

Read-only

Search the Facebook Ads Library for live ads matching the given queries.

Runs a remote scraper (30s–few minutes). Full results are saved to a JSON file; only a compact preview is returned inline. Use read_saved_results to page through the full dataset without flooding context.

ParametersJSON Schema

Name	Required	Description	Default
`ad_type`	No	Ad type filter: ALL, POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, EMPLOYMENT_ADS, or CREDIT_ADS.	ALL
`country`	No	ISO country code to filter by, e.g. 'US', 'IN', or 'ALL'. None for no filter.
`sort_by`	No	Sort order: SORT_BY_TOTAL_IMPRESSIONS or SORT_BY_RELEVANCY_MONTHLY_GROUPED.	SORT_BY_TOTAL_IMPRESSIONS
`end_date`	No	Latest ad delivery date in YYYY-MM-DD format. None for no upper bound.
`media_type`	No	Media type filter: ALL, IMAGE, MEME, IMAGE_AND_MEME, VIDEO, or NONE.	ALL
`start_date`	No	Earliest ad delivery date in YYYY-MM-DD format. None for no lower bound.
`active_status`	No	Ad status filter: ALL, ACTIVE, or INACTIVE.	ALL
`search_queries`	Yes	Keywords or brand names to search for, e.g. ['nike', 'adidas'].
`content_languages`	No	Language codes to filter ad content by, e.g. ['en', 'fr'].
`publisher_platforms`	No	Platforms to filter by, e.g. ['facebook', 'instagram'].
`max_results_per_query`	No	Maximum ads to return per query. Minimum 10 (actor limit).
`enrich_with_ad_details`	No	Fetch extra per-ad details. Slower and uses more Apify credits.

Output Schema

ParametersJSON Schema

Name	Required	Description
`ads`	Yes
`queries`	Yes
`file_path`	Yes
`result_count`	Yes

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral context beyond annotations: it runs a remote scraper with a time estimate, saves full results to a JSON file, and returns only a compact preview. This complements the readOnlyHint and openWorldHint annotations without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: first states the purpose, second explains the behavior. It is concise, front-loaded, and every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description adequately covers the tool's behavior, async nature, and file output. Minor gap: lack of clarity on how it relates to start_facebook_ads_scrape, but overall complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description only mentions 'queries' corresponding to the search_queries parameter without adding further details. No extra semantic value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches the Facebook Ads Library for live ads matching queries. It distinguishes from siblings like search_google or search_google_ads but does not differentiate from the sibling start_facebook_ads_scrape, which may have a similar purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description mentions the scraper takes 30s to few minutes and suggests using read_saved_results for full results, implying when to use it. However, it does not explicitly state when not to use it or compare with alternatives like start_facebook_ads_scrape.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_googleA

Read-only

Search Google for organic results to research brands, news, and ad context.

ParametersJSON Schema

Name	Required	Description
`queries`	Yes	Search queries to run, e.g. ['nike ad strategy 2025', 'adidas campaign news'].
`country_code`	No	2-letter country code controlling the Google domain, e.g. 'gb' → google.co.uk. None uses google.com.
`search_language`	No	Language code to filter results by, e.g. 'en', 'fr', 'de'.
`quick_date_range`	No	Relative date filter: d<N> (days), w<N> (weeks), m<N> (months), y<N> (years). E.g. 'd10', 'w2', 'm6'.
`results_per_page`	No	Results per page, between 10 and 100.
`max_pages_per_query`	No	Number of result pages per query. Each page contains ~10 results.

Output Schema

ParametersJSON Schema

Name	Required	Description
`queries`	Yes
`results`	Yes
`file_path`	Yes
`result_count`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds valuable behavioral context: it runs a remote scraper (30s–few minutes), saves full results to a JSON file, returns only a compact preview, and refers to read_saved_results for paging. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loading the purpose, then adding behavioral details. Every sentence is informative with no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity (remote scraper, multiple parameters, result storage), the description explains the asynchronous behavior, result handling, and how to access full results. The presence of an output schema covers return values, making this description complete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, with each parameter described. The description does not add further meaning beyond what the schema provides for parameters. Baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches Google for organic results, specifying the verb 'search', the resource 'Google for organic results', and the research purpose ('brands, news, and ad context'). It distinguishes from sibling tools like search_google_ads and search_facebook_ads.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use this tool vs. read_saved_results, explaining that full results are saved and only a compact preview is returned. However, it does not explicitly mention when not to use this tool or provide alternatives among other search siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_google_adsA

Read-only

Search the Google Ads Transparency Center for live ads by advertiser name or domain.

Returns headlines, formats, regions, days_active, and destination URLs. Runs a remote scraper (30s–few minutes). Full results are saved to a JSON file; only a compact preview is returned inline. Use read_saved_results to page through the full dataset without flooding context.

ParametersJSON Schema

Name	Required	Description
`region`	No	2-letter ISO country code to filter by, e.g. 'US', 'GB'. None for worldwide.
`end_date`	No	Latest last-shown date in YYYY-MM-DD format. None for no upper bound.
`start_date`	No	Earliest first-shown date in YYYY-MM-DD format. None for no lower bound.
`advertisers`	Yes	Brand names, domains (e.g. 'nike.com'), full URLs, or advertiser IDs starting with 'AR'. Mix formats freely.
`political_ads_only`	No	Restrict results to political and election ads only.
`max_ads_per_advertiser`	No	Maximum ads returned per advertiser. 0 means unlimited.

Output Schema

ParametersJSON Schema

Name	Required	Description
`ads`	Yes
`queries`	Yes
`file_path`	Yes
`result_count`	Yes

TDQS

A4.4/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that it runs a remote scraper with a 30-second to few-minute duration, saves full results to a JSON file, and returns only a compact preview inline. These details go beyond the readOnlyHint and openWorldHint annotations, providing valuable behavioral context for an agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, each serving a distinct purpose: stating the action and output, explaining the process and time, and directing to a related tool for full results. It is front-loaded and contains no superfluous text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, 1 required, output schema present), the description covers the essential behavior, timing, data handling, and provides a pointer to related tools. It does not detail every parameter, but the schema handles that, making the description sufficient for an agent to select this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description mentions searching 'by advertiser name or domain,' which aligns with the advertisers parameter description but does not add new semantic information beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches the Google Ads Transparency Center for live ads by advertiser name or domain, and lists the returned fields (headlines, formats, etc.). It distinguishes from sibling tools like search_facebook_ads (different platform) and read_saved_results (for full data), leaving no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit guidance to use read_saved_results for paging through full data, and mentions the remote scraper takes 30s–few minutes, setting expectations. However, it does not explicitly state when not to use this tool versus alternatives like start_google_ads_scrape, though the contrast is implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_instagram_profilesA

Read-only

Fetch public Instagram profile data including follower counts, bio, and recent posts.

ParametersJSON Schema

Name	Required	Description	Default
`profiles`	Yes	Instagram usernames to fetch, e.g. ['natgeo', 'nike'].
`include_recent_posts`	No	Also fetch each profile's recent posts (captions, likes, timestamps).

Output Schema

ParametersJSON Schema

Name	Required	Description
`profiles`	Yes
`file_path`	Yes
`result_count`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description adds behavioral context beyond annotations: remote scraper, time range, result storage method, and that only a compact preview is returned. Contradicts nothing in annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences are concise, front-loaded with purpose, behavioral context, and guidance. No wasteful or redundant phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With output schema present, description need not detail return values. It covers the scraping process, timing, and result handling. Lacks mention of error handling for missing profiles, but otherwise complete enough for a tool with good annotations and low parameter count.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. Description restates schema information for both parameters without adding new semantics. It does not explain the compact preview format or details beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'Fetch' and resource 'public Instagram profile data' with specifics (follower counts, bio, recent posts). It distinguishes from siblings like start_instagram_scrape and read_saved_results by implying this tool provides initial fetch and compact preview.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly mentions the remote scraper runs 30s–few minutes, results saved to JSON, and suggests using read_saved_results for full dataset. Provides clear context but does not explicitly exclude alternatives like start_instagram_scrape.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_facebook_ads_scrapeA

Start a Facebook Ads Library scrape in the background and return a run_id immediately.

Use this instead of search_facebook_ads when running multiple scrapers in parallel. Call check_run_status to monitor progress, then collect_scrape_results once SUCCEEDED.

ParametersJSON Schema

Name	Required	Description	Default
`ad_type`	No	Ad type filter: ALL, POLITICAL_AND_ISSUE_ADS, HOUSING_ADS, EMPLOYMENT_ADS, or CREDIT_ADS.	ALL
`country`	No	ISO country code to filter by, e.g. 'US', 'IN', or 'ALL'. None for no filter.
`sort_by`	No	Sort order: SORT_BY_TOTAL_IMPRESSIONS or SORT_BY_RELEVANCY_MONTHLY_GROUPED.	SORT_BY_TOTAL_IMPRESSIONS
`end_date`	No	Latest ad delivery date in YYYY-MM-DD format. None for no upper bound.
`media_type`	No	Media type filter: ALL, IMAGE, MEME, IMAGE_AND_MEME, VIDEO, or NONE.	ALL
`start_date`	No	Earliest ad delivery date in YYYY-MM-DD format. None for no lower bound.
`active_status`	No	Ad status filter: ALL, ACTIVE, or INACTIVE.	ALL
`search_queries`	Yes	Keywords or brand names to search for, e.g. ['nike', 'adidas'].
`content_languages`	No	Language codes to filter ad content by, e.g. ['en', 'fr'].
`publisher_platforms`	No	Platforms to filter by, e.g. ['facebook', 'instagram'].
`max_results_per_query`	No	Maximum ads to return per query. Minimum 10 (actor limit).
`enrich_with_ad_details`	No	Fetch extra per-ad details. Slower and uses more Apify credits.

Output Schema

ParametersJSON Schema

Name	Required	Description
`hint`	Yes
`run_id`	Yes
`status`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate this is not read-only and interacts with external systems. The description adds behavioral context: it runs in the background and returns immediately. It does not contradict annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences, front-loaded with purpose, then usage guidance, then workflow. No redundant information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 12 parameters and an output schema, the description covers the essential aspects: async nature, parallel usage, and follow-up steps. Could mention the underlying platform (Apify) but not necessary.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with well-described parameters. The description does not add parameter-specific meaning beyond the schema, which is acceptable given high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'start', the resource 'Facebook Ads Library scrape', and the output 'run_id'. It distinguishes from sibling tool 'search_facebook_ads' by explicitly mentioning parallel scraping.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly recommends using this tool instead of 'search_facebook_ads' when running multiple scrapers in parallel, and provides a clear workflow: call 'check_run_status', then 'collect_scrape_results' once SUCCEEDED.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_google_ads_scrapeA

Start a Google Ads Transparency Center scrape in the background and return a run_id immediately.

Use this instead of search_google_ads when running multiple scrapers in parallel. Call check_run_status to monitor progress, then collect_scrape_results once SUCCEEDED.

ParametersJSON Schema

Name	Required	Description
`region`	No	2-letter ISO country code to filter by, e.g. 'US', 'GB'. None for worldwide.
`end_date`	No	Latest last-shown date in YYYY-MM-DD format. None for no upper bound.
`start_date`	No	Earliest first-shown date in YYYY-MM-DD format. None for no lower bound.
`advertisers`	Yes	Brand names, domains (e.g. 'nike.com'), full URLs, or advertiser IDs starting with 'AR'. Mix formats freely.
`political_ads_only`	No	Restrict results to political and election ads only.
`max_ads_per_advertiser`	No	Maximum ads returned per advertiser. 0 means unlimited.

Output Schema

ParametersJSON Schema

Name	Required	Description
`hint`	Yes
`run_id`	Yes
`status`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds behavioral context beyond annotations: it explains the asynchronous, background nature and the pattern of polling for results. Annotations only indicate mutability (readOnlyHint=false) and variability (openWorldHint=true); the description elaborates well without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences with no wasted words. It front-loads the action, then provides usage guidance and workflow, achieving perfect conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (6 parameters, 1 required, output schema exists), the description is complete: it explains what the tool does, when to use it, and the subsequent steps needed. It does not need to detail output schema since that is provided separately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. The description does not add additional parameter meaning beyond what is already in the schema, so it meets the baseline but does not exceed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool starts a Google Ads Transparency Center scrape in the background and returns a run_id. It also distinguishes from the sibling tool search_google_ads, meeting the highest standard for purpose clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says 'Use this instead of search_google_ads when running multiple scrapers in parallel,' providing a clear alternative and the parallel use case. It also specifies the workflow of calling check_run_status and collect_scrape_results.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_instagram_scrapeA

Start an Instagram profile scrape in the background and return a run_id immediately.

Use this instead of search_instagram_profiles when running multiple scrapers in parallel. Call check_run_status to monitor progress, then collect_scrape_results once SUCCEEDED.

ParametersJSON Schema

Name	Required	Description	Default
`profiles`	Yes	Instagram usernames to fetch, e.g. ['natgeo', 'nike'].
`include_recent_posts`	No	Also fetch each profile's recent posts (captions, likes, timestamps).

Output Schema

ParametersJSON Schema

Name	Required	Description
`hint`	Yes
`run_id`	Yes
`status`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses asynchronous background execution, immediate return of run_id, and need for subsequent monitoring and collection. This goes beyond annotations (readOnlyHint false, openWorldHint true) by explaining the async pattern, though it does not mention auth or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, front-loaded with the primary action. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's async nature and the presence of sibling tools for monitoring and collection, the description adequately covers the workflow. It could mention what happens on failure or edge cases, but overall it is complete for its purpose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with clear descriptions. The description does not add additional semantics beyond what the schema already provides, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it starts an Instagram profile scrape in the background and returns a run_id immediately. It distinguishes from the sibling tool search_instagram_profiles by specifying parallel use case.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use this tool instead of search_instagram_profiles ('when running multiple scrapers in parallel'), and provides a workflow: call check_run_status then collect_scrape_results.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: managing background runs, retrieving results, or searching specific ad platforms. The blocking vs. async variants are well-differentiated by their names and descriptions.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern with lowercase underscores (e.g., search_facebook_ads, start_google_ads_scrape, collect_scrape_results). No mixing of conventions.

Tool Count5/5

11 tools cover the essential operations for an ad scraping server: searches (blocking and async) for multiple platforms, status checking, result collection, and saved results management. The count feels well-scoped.

Completeness4/5

The tool surface covers the full lifecycle of ad scraping—search, async start, status, collect, list, read. Missing are a delete or cancel capability, but these are minor given the domain.

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2
UnifAPI
com.unifapi
Hosted MCP server for live public-data APIs and Skills for AI agents.
Open Data Search AI & Machine Learning
2
GTM API: LinkedIn MCP Server
com.gtm-api
Managed LinkedIn MCP server for AI agents: search, connect, message and enrich on accounts you own.
Social Media Communication
15
MoltArch A
com.moltarch
Marketing intelligence API for AI agents. Real campaign data, not LLM guesses.
Marketing RAG Systems Research & Data
2

Related MCP Servers

synter-mcp-server
Marketing App Automation Social Media
Synter-Media-AI
A
license
A
quality
C
maintenance
MCP server for AI agents to manage ad campaigns across Google, Meta, LinkedIn, Microsoft, Reddit, TikTok, and more
Updated 16 hours ago (2026-09-02 21:16 UTC)
21
278
17
MIT
google-ads-transparency-mcp
Web Scraping Marketing
block-town
A
license
A
quality
F
maintenance
An MCP server that lets AI assistants look up any advertiser's Google ads. Search by domain or company name, retrieve ad creatives, and decode text ad content from Google's Ads Transparency Center.
Updated 5 months ago (2026-03-26 18:16 UTC)
4
6
MIT
gads-transparency-mcp
Web Scraping Browser Automation
lionkiii
A
license
A
quality
F
maintenance
A Model Context Protocol server that enables AI assistants to research competitor ads, analyze advertiser profiles, and compare ad presence across 42 regions using publicly available Google Ads Transparency data.
Updated 6 months ago (2026-03-09 05:39 UTC)
5
30
1
MIT
Meta Ads MCP
Marketing Social Media
JavierDaimiel
A
license
Not graded
quality
B
maintenance
A Model Context Protocol server that lets AI assistants run your Meta Ads end to end — launch campaigns, upload creatives, update budgets, and dig into performance through natural conversation. Works across Facebook, Instagram, and other Meta surfaces.
Updated 2 months ago (2026-06-19 10:06 UTC)
Business Source 1.1

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/rugvedp/all-about-ads-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server