Skip to content

AdLemur MCP

Bring sourced ad research into your agent

AdLemur is an ad library MCP server. Connect Claude, ChatGPT, Codex, Cursor or any MCP client, and your agent reads competitor ads collected from each platform's public ad library, with source, date and geography on every record. It works from the same project-scoped evidence as the AdLemur app. Stored reads use no provider credits.

Server URL

https://app.adlemur.com/mcp

Connect a client

The server speaks streamable HTTP and signs you in with OAuth. The same steps are in Settings → Agent inside the app.

Claude Code

claude mcp add --transport http --scope user adlemur https://app.adlemur.com/mcp

Approve the AdLemur login when prompted.

Codex

codex mcp add adlemur --url https://app.adlemur.com/mcp

In Codex Desktop: Settings → Integrations & MCP → Add your own, paste the URL.

Claude Desktop

Settings → Connectors → Add custom connector, paste the URL and approve the login. Needs a Claude Pro, Max, Team or Enterprise plan.

ChatGPT

Settings → Apps & Connectors → Advanced settings → turn on Developer mode. Then Create a connector named AdLemur, paste the URL and choose OAuth.

API keys for scripts and headless agents

On the hosted service, create a key in Settings → Agent. Keys start with oseo_ and belong to your workspace. Send one as Authorization: Bearer oseo_… or an x-api-key header instead of signing in. Revoking a key stops its clients at once.

claude mcp add --transport http adlemur https://app.adlemur.com/mcp \
  --header 'Authorization: Bearer ${ADLEMUR_API_KEY}'

Each key is limited to 500 requests a minute. A bad or revoked key returns 401 invalid_api_key; going over the limit returns 429 rate_limited with a Retry-After header. Everything else, including write approval, works the same as with OAuth.

What an agent can change

  • Read (52 tools) never changes anything. Stored reads cost no credits.
  • Write (45 tools) changes your project or, for the owned tools, a connected ad account. Connecting through OAuth grants no write permission by itself.
  • Paid (7 tools) can spend provider credits. Each has an estimate tool: the agent shows the maximum charge and scope and gets your approval first.
  • Ad-account writes cover Google, Meta, TikTok and LinkedIn. They are off by default and need the deployment switch, the project setting, write-capable provider access and a daily budget ceiling. New campaigns are created paused, non-UI writes are rate-limited per project, and provider deletes are unsupported.
  • Your workspace role applies: a viewer can call read tools only. Approval of an exact change is enforced by your client, so keep approval on for write tools.

104 tools

Plus whoami, list_projects and create_project to choose the workspace project. Agents can also read the guide adlemur://guides/research-competitor-ads.

Setup

  • get_source_health

    Check source readiness · Inspect provider configuration, freshness, safe failures, usage, and recovery guidance.

    read
  • add_competitor

    Add a watchlist brand · Add a normalized brand and domain to the project watchlist, as a competitor or as inspiration, without calling a provider.

    write
  • find_advertiser_identities

    Find advertiser identities · Find candidate public-ad identities from a competitor website for user review.

    read
  • discover_meta_advertisers

    Discover advertisers by keyword · Find up to 20 Meta Ad Library advertisers for a keyword and country, as candidates to review, not tracked brands.

    read
  • confirm_advertiser_identity

    Confirm an advertiser identity · Save one reviewed identity from an enabled first-party public-ad source.

    write
  • get_channel_discovery

    Read profile review evidence · Inspect advertiser and social candidates, decisions, and ownership evidence.

    read
  • decide_channel_candidate

    Review a profile candidate · Confirm, reject, or reopen an explicit candidate without approving paid collection.

    write
  • preview_channel_url

    Preview a profile URL · Save a supported profile URL as a candidate for review.

    write
  • refresh_channel_discovery

    Refresh profile discovery · Queue discovery under an explicitly approved provider allowance.

    paid
  • remove_social_profile

    Remove a social connection · Remove a local social profile connection without deleting upstream profiles.

    write
  • list_competitor_suggestions

    List suggested competitors · Read stored competitor suggestions seeded from the project's own domain.

    read
  • suggest_competitors

    Suggest competitors · Find competitors from the project's own Google keywords, at most once a day and without using workspace credits.

    write
  • list_owned_ad_accounts

    List live owned ad accounts · List Google Ads or Meta ad accounts visible to the connected credential and show project bindings.

    read
  • start_owned_ad_connection

    Start an owned ad connection · Generate a provider consent link so the account owner can connect or reconnect an ad profile.

    write
  • bind_owned_ad_accounts

    Bind owned ad accounts · Select connected ad accounts for a project and grant read or write access after approval.

    write
  • get_owned_ad_readiness

    Inspect owned ad readiness · Read live account and campaign review evidence, with explicit unavailable checks. Does not authorize a launch.

    read
  • get_meta_business_asset_ownership

    Check Meta business asset ownership · Check exact Page, Instagram, and bound ad-account ownership in specified Meta business portfolios.

    read
  • search_ad_platform_help

    Find official platform help · Return official Google Ads API or Meta Marketing API guidance and release-note links.

    read
  • get_owned_ad_diagnostics

    Validate an owned ad connection · Validate a Google Ads or Meta credential and update its safe connection health.

    write
  • get_owned_account_settings

    Read Google account settings · Google Ads only. See which auto-apply recommendations Google can apply to every campaign in the account by itself.

    read
  • update_owned_account_settings

    Turn off Google auto-apply · Google Ads only. Turn off auto-apply recommendations for an account, so Google stops changing campaigns by itself. Owners and admins only.

    write

Monitor

  • list_competitors

    List watchlist brands · Read the project's watchlist with each brand's role, plus its source identities.

    read
  • sync_public_ads

    Collect public competitor ads · Collect every available public-ad page for a confirmed advertiser identity without a provider charge.

    write
  • search_ads

    Search competitor ads · Search stored, sourced ads without triggering collection.

    read
  • get_ad

    Get ad history · Inspect one ad's observations, changes, and source coverage.

    read
  • get_ad_image_text

    Read Google ad image text · Read cached OCR or explicitly extract visible text from a Google screenshot ad using local OCR. Results are derived, not Google-reported copy.

    write
  • get_ad_media

    View a Google ad image · Return a stored Google ad's image creative, downscaled, through the browser collector.

    read
  • list_ad_changes

    List ad changes · Read recent ad and paid-keyword changes with immutable observation provenance.

    read
  • record_paid_media_evidence

    Record paid-media evidence · Log a sponsorship, podcast read, event, creator, or affiliate placement with a mandatory source URL.

    write
  • list_paid_media_evidence

    List paid-media evidence · Read a competitor's analyst-recorded and site-derived paid media, each with its source URL.

    read
  • collect_site_paid_media

    Collect site paid-media signals · Read a competitor's own pages for redirects, form vendors, CTA structure, and affiliate terms. Uses no credits.

    write

Research

  • research_paid_keywords

    Research paid keywords · Read the latest stored snapshot without making a DataForSEO call.

    read
  • research_keyword

    Research one keyword · Fetch one keyword's live ad block and related keyword ideas. Charges per part requested.

    paid
  • estimate_paid_search_refresh

    Estimate paid-keyword refresh · Calculate the current DataForSEO ceiling without making a provider call.

    read
  • refresh_paid_search

    Refresh paid-keyword evidence · Run one user-approved paid-keyword refresh with a server-validated ceiling.

    paid
  • get_competitor_monitoring

    Read weekly competitor watching · Report which parts of a competitor are watched weekly and the combined weekly ceiling enabling would authorise.

    read
  • set_competitor_monitoring

    Watch a competitor weekly · Turn weekly ad-profile syncs and paid-keyword snapshots on or off together; enabling authorises a combined recurring weekly charge.

    paid
  • list_paid_competitor_candidates

    List paid competitors · Read stored shared-keyword competitor discovery without triggering DataForSEO spend.

    read
  • estimate_paid_competitor_discovery

    Estimate paid-competitor discovery · Validate stored seed keywords and calculate the current discovery ceiling.

    read
  • refresh_paid_competitor_discovery

    Refresh paid-competitor discovery · Run one approved shared-keyword competitor discovery request.

    paid
  • compare_advertisers

    Compare advertisers · Compare stored observations only within compatible provider, platform, and geography scopes.

    read
  • get_competitor_dossier

    Roll a competitor up across platforms · One competitor across every platform, each row carrying its own coverage statement.

    read
  • get_competitor_lifecycle

    Get competitor ad lifecycle · How fast a competitor launches and stops ads, and how old its running ads are.

    read
  • get_competitor_store

    Read a competitor's online store · Store platform, pixels and tools, catalogue size, newest products, best sellers and price changes from the competitor's own site.

    read
  • get_competitor_traffic

    Read a competitor's estimated search traffic · Stored estimates of monthly visits from Google search results for one competitor domain in one market, with the ranking keyword count. Not total website visits.

    read
  • estimate_competitor_traffic_refresh

    Estimate a search-traffic refresh · The maximum DataForSEO charge for one competitor search-traffic estimate. No provider call.

    read
  • refresh_competitor_traffic

    Refresh a competitor's estimated search traffic · Run one user-approved DataForSEO search-traffic estimate with a server-validated ceiling. Charges the account, including when the provider holds no data for the domain.

    paid
  • get_ad_report

    Get a saved ad report · Resolve a saved report to retained evidence and source URLs without provider spend.

    read
  • save_ad_evidence

    Save ads · Save stored competitor ads so they can be analyzed and turned into drafts.

    write
  • list_saved_evidence

    List saved ads · List saved ads with the ids creative analysis needs.

    read
  • get_owned_keyword_plan

    Research with Google Keyword Planner · Read first-party keyword ideas and historical estimates for a bound account, with no paid fallback.

    read
  • get_owned_reach_estimate

    Estimate Meta audience size · Read Meta's native audience-size bounds for a targeting choice. Missing bounds stay unavailable, never zero.

    read

Create

  • analyze_creatives

    Analyze saved creatives · Run paid analysis and store original concepts and variants.

    paid
  • create_ad_brief

    Save an ad brief · Update an original brief in the AdLemur workspace.

    write
  • get_brand

    Read the Brand section · The brand inputs saved on the Brand page, read before any ad, script or caption.

    read
  • update_brand

    Change the Brand section · Edit one Brand input on request, from text and lists to colours, products and competitors; shown on the page as made by the agent.

    write
  • fill_brand

    Fill in the Brand section in one call · Apply up to 60 Brand changes at once, so an agent can complete the whole profile; shown on the page as made by the agent.

    write
  • inspect_brand_site

    Read a brand's website · Read the public site for the brand's description, products, prices, logo, colours and images, to fill the Brand section. No credits.

    read
  • add_brand_media

    Add logos, photos and videos to the Brand section · Save up to 12 logos, product photos, demo videos or screenshots from public links onto the Brand page. No credits.

    write
  • get_creative_lineage

    Get creative lineage · Read accepted links between creative and owned outcomes.

    read
  • preview_owned_ad_resource

    Preview a Meta resource change · Read current provider state and issue a short-lived signed preview for an allowlisted Meta resource operation, including SPLIT_TEST ad studies.

    read
  • set_deployment_write_cap

    Set the deployment agent ad-write cap · Set the deployment-wide bound on how high any project's agent ad-write ceiling may go. Refused on hosted deployments.

    write
  • prepare_owned_creative

    Prepare an owned Creative · Edit or import Creative copy and imagery and mark it launch-ready, optionally with an explicit MCP write ceiling, without OpenRouter or a provider call.

    write
  • retire_owned_creatives

    Retire owned Creatives · Take obsolete stored Creatives out of the launch-ready list. Running ads and their history are unchanged.

    write
  • preview_owned_launch

    Preview one campaign launch plan · Review paused campaign trees, budgets, audiences and creative evidence together before approval.

    read
  • launch_owned_campaigns

    Launch an approved campaign plan · Start the signed reviewed plan with existing spend safeguards and explicit partial-failure recovery.

    write
  • create_owned_campaign

    Create an owned campaign · Create a non-delivering campaign from a stored AdLemur creative when writes are enabled. Google Search and Meta support traffic or leads; other providers support traffic. Meta website leads require a dataset ID. Approval metadata, political-advertising and LinkedIn EU declarations, and budget enforcement apply.

    write
  • clone_owned_ad

    Clone an owned ad with one change · Meta only. Copy a live ad into a new paused ad set with one change (offer, hook, body, image, or countries), leaving the original and its learning untouched.

    write
  • create_owned_ad_group

    Add a Google Search ad group · Google Ads only. Add a named ad group with keywords, an optional bid, and one responsive search ad to an existing Search campaign.

    write
  • edit_owned_search_ad

    Edit a Google search ad · Google Ads only. Change the headlines, descriptions, final URL, display paths, or pins of a paused responsive search ad in place.

    write
  • update_owned_assets

    Update Google sitelinks, callouts and images · Google Ads only. Add or unlink sitelinks, callouts, structured snippets, and images stored in AdLemur on a campaign or ad group in one audited batch.

    write
  • replace_owned_ad_creative

    Replace an owned ad creative · Create a replacement ad from a launch-ready Creative, verify it, and pause the old ad under the existing write policy and approval controls.

    write
  • mutate_owned_ad_resource

    Change a Meta resource · Execute an exact signed preview for allowlisted Meta campaign, ad set, ad, creative, and SPLIT_TEST ad study operations.

    write

Results

  • get_ad_business_context

    Read advertising business context · Saved business goals, channel roles, measurement and economics; no provider changes.

    read
  • model_acquisition_funnel

    Model acquisition economics · Model explicit acquisition-funnel assumptions without saving or spending.

    read
  • get_owned_performance

    Get owned performance · Read compatible first-party reporting scopes and freshness.

    read
  • check_owned_tracking

    Check website tracking evidence · Inspect source-level GA4, Meta pixel and LinkedIn Insight Tag IDs without claiming conversions fired.

    read
  • get_google_conversion_actions

    Inspect Google conversion actions · Read live action settings and historical conversion observations without sending test events.

    read
  • get_crm_outcomes

    Read live CRM outcomes · Read matched Twenty CRM lead cohorts, current stages, deal values and unmatched leads.

    read
  • list_owned_recommendations

    List owned recommendations · Read deterministic issues backed by stored provider facts.

    read
  • list_owned_reports

    List owned reports · Read saved My Ads performance report templates.

    read
  • save_owned_report

    Save an owned report · Create or update a saved My Ads performance report.

    write
  • delete_owned_report

    Delete an owned report · Delete a saved report without deleting performance data.

    write
  • list_owned_rules

    List owned rules · Read alert-only My Ads rules and their conditions.

    read
  • save_owned_rule

    Save an owned rule · Create or update an alert-only rule that cannot change delivery or budgets.

    write
  • delete_owned_rule

    Delete an owned rule · Delete a My Ads rule and stop its future evaluations.

    write
  • record_owned_outcomes

    Log sales results · Log daily bookings, shows and closed deals for a campaign or ad.

    write
  • remove_owned_outcome_day

    Remove a logged sales day · Remove mistaken campaign or ad results for one date before switching reporting levels. Other logged days are retained.

    write
  • list_alert_destinations

    List alert destinations · Read the Slack and webhook destinations rules can post to.

    read
  • save_alert_destination

    Save an alert destination · Add or update a Slack or signed webhook destination for rule matches.

    write
  • test_alert_destination

    Send a test alert · Post one test message to a saved destination.

    write
  • get_creative_lifecycle

    Get creative lifecycle · Read creative churn, hit rate and spend by ad age.

    read
  • get_owned_campaigns

    Get owned campaigns · Read connected accounts, launch-ready creatives, campaigns, ads, budgets, versions, and write audits.

    read
  • query_owned_ad_resources

    Query live owned ad resources · Run bounded read-only GAQL or list/get allowlisted Meta account resources and business-scoped ad studies without exposing credentials.

    read
  • get_owned_ad_report

    Read a named native ad report · Read bounded native report recipes and recommendation estimates. No apply/dismiss; use a report job for backfills.

    read
  • start_owned_report_job

    Start a Meta historical report · Start a resumable Meta async Insights backfill in windows, stored for later reads. No ad changes.

    write
  • get_owned_report_job

    Check a Meta historical report · Read backfill progress, per-window coverage and stored daily rows, page by page.

    read
  • get_owned_ad_resource_metadata

    Describe owned ad resources · Read Google Ads field metadata or AdLemur' safe Meta resource capabilities.

    read
  • sync_owned_performance

    Sync owned performance · Fetch and store normalized performance for all connected project accounts over a bounded date range.

    write
  • update_owned_ad

    Update an owned ad · Pause, activate, archive a paused campaign, or change a supported daily budget when provider writes are enabled and the request carries approval metadata.

    write
  • set_owned_campaign_status

    Start or pause a campaign · Start or pause a campaign with all of its ads in one approved change.

    write
  • update_owned_keywords

    Update owned keywords and negatives · Google Ads only. Add, remove, or pause keywords and negative keywords on a campaign or ad group in one atomic, audited batch.

    write
  • update_owned_audience

    Update a Google Ads audience · Google Ads only. Add or remove campaign locations and languages or ad-group audience segments and age exclusions in one approved, audited batch.

    write
  • set_owned_bid

    Set an owned Google Ads bid · Google Ads only. Set an ad-group max-CPC bid or a campaign Maximize Clicks bid ceiling, held under the currency's agent write ceiling.

    write

Using Meta's own Ads MCP as well? It manages your ad accounts but cannot see competitors. Read what Meta Ads MCP reaches and what each ad library covers.