LinkedIn Ads MCP: Ad Library tools and limits
How Proxy's LinkedIn Ads MCP reads the LinkedIn Ad Library: search by company or keyword, the one-year date window, paging tokens, fields and credit cost.
Proxy connects an assistant to the public LinkedIn Ad Library. It can pull any company’s LinkedIn ads or search every advertiser by keyword. It is read-only and never connects to Campaign Manager.
This page documents exactly how the two LinkedIn tools behave. For the short parameter tables, see the LinkedIn tool reference.
Connect
One endpoint serves every client and every platform:
https://mcp.useproxy.dev/mcp?ref=docs
Sign-in is OAuth, with no API keys. Steps per client are in Connect your client, with deeper notes for Claude, ChatGPT and Claude Code.
Which tool fires when
| You ask for | Tool chain |
|---|---|
| A company’s LinkedIn ads | search_linkedin_ads with company_name |
| Ads about a topic | search_linkedin_ads with keyword |
| More of the same search | search_linkedin_ads with the pagination_token |
| Targeting or impressions for one ad | get_linkedin_ad_details with the ad id |
There is no separate ID lookup step. A company name goes straight into the search.
search_linkedin_ads
| Parameter | Default | Accepted values and behaviour |
|---|---|---|
company_name |
none | Advertiser name. company is accepted as an alias |
keyword |
none | Free text, searched across all advertisers |
company_id |
none | LinkedIn company ID, for a precise match |
countries |
all | Comma-separated ISO codes, for example US,CA,MX |
start_date |
none | YYYY-MM-DD |
end_date |
none | YYYY-MM-DD |
pagination_token |
none | The paginationToken from the previous page |
At least one of company_name, keyword or company_id is required. A call with none returns an error.
How dates are handled
LinkedIn needs both dates, and both must sit between 365 days ago and yesterday. So when you set either date:
- A missing
start_datebecomes 365 days ago. - A missing
end_datebecomes yesterday. - A date outside the window is moved to its edge.
When anything was filled in or moved, the response includes “Date range used” with the actual range. With no dates at all, none are sent.
What each ad contains
Every row carries id, advertiser, poster, adType, description, has_image, has_video, has_carousel, totalImpressions, impressionsByCountry, startDate and ad_url.
descriptionis cut to the first 100 characters in search results. The full text is in the ad details.posteris the display name on the ad unit. It can differ fromadvertiser.totalImpressionsis a range string such as5k-10k, never a count. It can be empty for running ads.startDatecan be empty for running ads.
The response also carries paginationToken and isLastPage.
get_linkedin_ad_details
| Parameter | Type | Behaviour |
|---|---|---|
ad_id |
string | The id from a search result. One ad per call |
Returns id, advertiser, poster, adType, description, headline, image, video, cta, destinationUrl, targeting, totalImpressions, impressionsByCountry, startDate, endDate and adDuration.
targetingcan be an empty object. LinkedIn does not expose it for every ad.impressionsByCountryis a list of country and share pairs. Shares are percentage strings such as100%orless than 1%.headlinecan be empty. Not every ad type has one.startDate,endDateandadDurationcan be empty for running ads.- An
imageURL can be passed to analyze_ad_image.
What it never contains
- Spend, clicks, leads or bids.
- Exact impression counts. Only ranges.
- Ads last shown more than a year ago.
- Guaranteed targeting data. Treat an empty
targetingas “not exposed”, not “untargeted”.
Paging
- Each call returns one page.
- When
isLastPageis false, passpaginationTokenback aspagination_tokento get the next page. - Keep the same search parameters when you page.
Credit cost
| Call | Credits |
|---|---|
search_linkedin_ads |
1 per call, so 1 per page |
get_linkedin_ad_details |
1 per ad |
Free is 20 credits a day with no card, Pro is $50 a month for 100 a day, and Max is $100 a month for 250 a day. There is no overage billing. See Credits and plans.
Failure modes
| Situation | What the tool returns |
|---|---|
| No company, keyword or ID | An error naming the three options |
| No matching ads | Zero ads and a hint to use fewer filters or a shorter company name |
| Date outside the past year | Results for the adjusted range, with “Date range used” |
Wrong or removed ad_id |
“Failed to retrieve LinkedIn ad details” and a prompt to check the ID |
| Rate limit, timeout or outage | A short retry hint. Raw upstream errors are never passed through |
Worked prompts
Pull [company]'s LinkedIn ads and group them by the audience each one speaks to.
search_linkedin_ads with company_name. 1 credit.
Which companies advertise on LinkedIn around "SOC 2 compliance" in the US and UK?
search_linkedin_ads with keyword and countries US,GB. 1 credit.
Show [company]'s LinkedIn ads since 1 January two years ago.
search_linkedin_ads with start_date. The date is moved to 365 days ago and the response says so. 1 credit.
Get the next two pages of that search.
Two search_linkedin_ads calls with pagination_token. 2 credits.
For the three newest ads, show targeting and the country split of impressions.
Three get_linkedin_ad_details calls. 3 credits.