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/mcpConnect 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/mcpApprove the AdLemur login when prompted.
Codex
codex mcp add adlemur --url https://app.adlemur.com/mcpIn 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
ownedtools, 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_healthCheck source readiness · Inspect provider configuration, freshness, safe failures, usage, and recovery guidance.
readadd_competitorAdd a watchlist brand · Add a normalized brand and domain to the project watchlist, as a competitor or as inspiration, without calling a provider.
writefind_advertiser_identitiesFind advertiser identities · Find candidate public-ad identities from a competitor website for user review.
readdiscover_meta_advertisersDiscover advertisers by keyword · Find up to 20 Meta Ad Library advertisers for a keyword and country, as candidates to review, not tracked brands.
readconfirm_advertiser_identityConfirm an advertiser identity · Save one reviewed identity from an enabled first-party public-ad source.
writeget_channel_discoveryRead profile review evidence · Inspect advertiser and social candidates, decisions, and ownership evidence.
readdecide_channel_candidateReview a profile candidate · Confirm, reject, or reopen an explicit candidate without approving paid collection.
writepreview_channel_urlPreview a profile URL · Save a supported profile URL as a candidate for review.
writerefresh_channel_discoveryRefresh profile discovery · Queue discovery under an explicitly approved provider allowance.
paidremove_social_profileRemove a social connection · Remove a local social profile connection without deleting upstream profiles.
writelist_competitor_suggestionsList suggested competitors · Read stored competitor suggestions seeded from the project's own domain.
readsuggest_competitorsSuggest competitors · Find competitors from the project's own Google keywords, at most once a day and without using workspace credits.
writelist_owned_ad_accountsList live owned ad accounts · List Google Ads or Meta ad accounts visible to the connected credential and show project bindings.
readstart_owned_ad_connectionStart an owned ad connection · Generate a provider consent link so the account owner can connect or reconnect an ad profile.
writebind_owned_ad_accountsBind owned ad accounts · Select connected ad accounts for a project and grant read or write access after approval.
writeget_owned_ad_readinessInspect owned ad readiness · Read live account and campaign review evidence, with explicit unavailable checks. Does not authorize a launch.
readget_meta_business_asset_ownershipCheck Meta business asset ownership · Check exact Page, Instagram, and bound ad-account ownership in specified Meta business portfolios.
readsearch_ad_platform_helpFind official platform help · Return official Google Ads API or Meta Marketing API guidance and release-note links.
readget_owned_ad_diagnosticsValidate an owned ad connection · Validate a Google Ads or Meta credential and update its safe connection health.
writeget_owned_account_settingsRead Google account settings · Google Ads only. See which auto-apply recommendations Google can apply to every campaign in the account by itself.
readupdate_owned_account_settingsTurn 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_competitorsList watchlist brands · Read the project's watchlist with each brand's role, plus its source identities.
readsync_public_adsCollect public competitor ads · Collect every available public-ad page for a confirmed advertiser identity without a provider charge.
writesearch_adsSearch competitor ads · Search stored, sourced ads without triggering collection.
readget_adGet ad history · Inspect one ad's observations, changes, and source coverage.
readget_ad_image_textRead 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.
writeget_ad_mediaView a Google ad image · Return a stored Google ad's image creative, downscaled, through the browser collector.
readlist_ad_changesList ad changes · Read recent ad and paid-keyword changes with immutable observation provenance.
readrecord_paid_media_evidenceRecord paid-media evidence · Log a sponsorship, podcast read, event, creator, or affiliate placement with a mandatory source URL.
writelist_paid_media_evidenceList paid-media evidence · Read a competitor's analyst-recorded and site-derived paid media, each with its source URL.
readcollect_site_paid_mediaCollect 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_keywordsResearch paid keywords · Read the latest stored snapshot without making a DataForSEO call.
readresearch_keywordResearch one keyword · Fetch one keyword's live ad block and related keyword ideas. Charges per part requested.
paidestimate_paid_search_refreshEstimate paid-keyword refresh · Calculate the current DataForSEO ceiling without making a provider call.
readrefresh_paid_searchRefresh paid-keyword evidence · Run one user-approved paid-keyword refresh with a server-validated ceiling.
paidget_competitor_monitoringRead weekly competitor watching · Report which parts of a competitor are watched weekly and the combined weekly ceiling enabling would authorise.
readset_competitor_monitoringWatch a competitor weekly · Turn weekly ad-profile syncs and paid-keyword snapshots on or off together; enabling authorises a combined recurring weekly charge.
paidlist_paid_competitor_candidatesList paid competitors · Read stored shared-keyword competitor discovery without triggering DataForSEO spend.
readestimate_paid_competitor_discoveryEstimate paid-competitor discovery · Validate stored seed keywords and calculate the current discovery ceiling.
readrefresh_paid_competitor_discoveryRefresh paid-competitor discovery · Run one approved shared-keyword competitor discovery request.
paidcompare_advertisersCompare advertisers · Compare stored observations only within compatible provider, platform, and geography scopes.
readget_competitor_dossierRoll a competitor up across platforms · One competitor across every platform, each row carrying its own coverage statement.
readget_competitor_lifecycleGet competitor ad lifecycle · How fast a competitor launches and stops ads, and how old its running ads are.
readget_competitor_storeRead 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.
readget_competitor_trafficRead 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.
readestimate_competitor_traffic_refreshEstimate a search-traffic refresh · The maximum DataForSEO charge for one competitor search-traffic estimate. No provider call.
readrefresh_competitor_trafficRefresh 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.
paidget_ad_reportGet a saved ad report · Resolve a saved report to retained evidence and source URLs without provider spend.
readsave_ad_evidenceSave ads · Save stored competitor ads so they can be analyzed and turned into drafts.
writelist_saved_evidenceList saved ads · List saved ads with the ids creative analysis needs.
readget_owned_keyword_planResearch with Google Keyword Planner · Read first-party keyword ideas and historical estimates for a bound account, with no paid fallback.
readget_owned_reach_estimateEstimate Meta audience size · Read Meta's native audience-size bounds for a targeting choice. Missing bounds stay unavailable, never zero.
read
Create
analyze_creativesAnalyze saved creatives · Run paid analysis and store original concepts and variants.
paidcreate_ad_briefSave an ad brief · Update an original brief in the AdLemur workspace.
writeget_brandRead the Brand section · The brand inputs saved on the Brand page, read before any ad, script or caption.
readupdate_brandChange 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.
writefill_brandFill 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.
writeinspect_brand_siteRead 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.
readadd_brand_mediaAdd 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.
writeget_creative_lineageGet creative lineage · Read accepted links between creative and owned outcomes.
readpreview_owned_ad_resourcePreview 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.
readset_deployment_write_capSet 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.
writeprepare_owned_creativePrepare 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.
writeretire_owned_creativesRetire owned Creatives · Take obsolete stored Creatives out of the launch-ready list. Running ads and their history are unchanged.
writepreview_owned_launchPreview one campaign launch plan · Review paused campaign trees, budgets, audiences and creative evidence together before approval.
readlaunch_owned_campaignsLaunch an approved campaign plan · Start the signed reviewed plan with existing spend safeguards and explicit partial-failure recovery.
writecreate_owned_campaignCreate 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.
writeclone_owned_adClone 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.
writecreate_owned_ad_groupAdd 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.
writeedit_owned_search_adEdit 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.
writeupdate_owned_assetsUpdate 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.
writereplace_owned_ad_creativeReplace 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.
writemutate_owned_ad_resourceChange 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_contextRead advertising business context · Saved business goals, channel roles, measurement and economics; no provider changes.
readmodel_acquisition_funnelModel acquisition economics · Model explicit acquisition-funnel assumptions without saving or spending.
readget_owned_performanceGet owned performance · Read compatible first-party reporting scopes and freshness.
readcheck_owned_trackingCheck website tracking evidence · Inspect source-level GA4, Meta pixel and LinkedIn Insight Tag IDs without claiming conversions fired.
readget_google_conversion_actionsInspect Google conversion actions · Read live action settings and historical conversion observations without sending test events.
readget_crm_outcomesRead live CRM outcomes · Read matched Twenty CRM lead cohorts, current stages, deal values and unmatched leads.
readlist_owned_recommendationsList owned recommendations · Read deterministic issues backed by stored provider facts.
readlist_owned_reportsList owned reports · Read saved My Ads performance report templates.
readsave_owned_reportSave an owned report · Create or update a saved My Ads performance report.
writedelete_owned_reportDelete an owned report · Delete a saved report without deleting performance data.
writelist_owned_rulesList owned rules · Read alert-only My Ads rules and their conditions.
readsave_owned_ruleSave an owned rule · Create or update an alert-only rule that cannot change delivery or budgets.
writedelete_owned_ruleDelete an owned rule · Delete a My Ads rule and stop its future evaluations.
writerecord_owned_outcomesLog sales results · Log daily bookings, shows and closed deals for a campaign or ad.
writeremove_owned_outcome_dayRemove a logged sales day · Remove mistaken campaign or ad results for one date before switching reporting levels. Other logged days are retained.
writelist_alert_destinationsList alert destinations · Read the Slack and webhook destinations rules can post to.
readsave_alert_destinationSave an alert destination · Add or update a Slack or signed webhook destination for rule matches.
writetest_alert_destinationSend a test alert · Post one test message to a saved destination.
writeget_creative_lifecycleGet creative lifecycle · Read creative churn, hit rate and spend by ad age.
readget_owned_campaignsGet owned campaigns · Read connected accounts, launch-ready creatives, campaigns, ads, budgets, versions, and write audits.
readquery_owned_ad_resourcesQuery live owned ad resources · Run bounded read-only GAQL or list/get allowlisted Meta account resources and business-scoped ad studies without exposing credentials.
readget_owned_ad_reportRead a named native ad report · Read bounded native report recipes and recommendation estimates. No apply/dismiss; use a report job for backfills.
readstart_owned_report_jobStart a Meta historical report · Start a resumable Meta async Insights backfill in windows, stored for later reads. No ad changes.
writeget_owned_report_jobCheck a Meta historical report · Read backfill progress, per-window coverage and stored daily rows, page by page.
readget_owned_ad_resource_metadataDescribe owned ad resources · Read Google Ads field metadata or AdLemur' safe Meta resource capabilities.
readsync_owned_performanceSync owned performance · Fetch and store normalized performance for all connected project accounts over a bounded date range.
writeupdate_owned_adUpdate 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.
writeset_owned_campaign_statusStart or pause a campaign · Start or pause a campaign with all of its ads in one approved change.
writeupdate_owned_keywordsUpdate 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.
writeupdate_owned_audienceUpdate 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.
writeset_owned_bidSet 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.