Skip to main content
Glama
LinkedIn Ads Library MCP Server

LinkedIn Ads Library MCP Server

Proxy — LinkedIn Ads Library Hosted MCP

LinkedIn Ads Library MCP Server

TIP

Proxy (useproxy.dev) is the free hosted version of this server. One connection gives ChatGPT, Claude, Cursor and any MCP client live ads from the Meta, Google, LinkedIn and TikTok (EU) ad libraries, with no API keys and 20 free credits a day. Use it in 2 minutes →

WARNING

This repo is the open-source, self-hosted LinkedIn server, for personal use and tinkering. It covers one platform, you pay ScrapeCreators for every call (about $1.88 per 1,000 after 100 free credits), and it doesn't get every feature hosted Proxy has. For client work or a team,use hosted Proxy.

This is a Model Context Protocol (MCP) server for the LinkedIn Ad Library.

With this you can search LinkedIn's public ad library for any company or brand, see what they're currently running and analyze their advertising. You can analyze ad images/text, analyze video ads with comprehensive insights, compare companies' strategies, and get insights into what's working in their campaigns.

Here's an example of what you can do when it's connected to Claude.


The easiest way to use the LinkedIn Ads Library MCP is the hosted version from Proxy (useproxy.dev). No API keys, no Gemini key, no Python, no server to run — just connect and start querying.

  • ⚡ Zero setup — nothing to install, configure, or maintain

  • 🔑 No API keys — skip the ScrapeCreators and Gemini keys entirely

  • 🔌 Works everywhere — ChatGPT, Claude, Cursor, Manus, and anywhere else that supports MCP

  • 🚀 Always up to date — new tools and fixes ship automatically

👉 Get started for free at useproxy.dev →

Prefer to run it yourself? The full self-host setup is documented below.

Hosted vs. Self-Host

Hosted: Proxy (useproxy.dev)

Self-host (this repo)

Ad libraries

Meta, Google, LinkedIn and TikTok (EU) in one server

LinkedIn only

Cost

Free for 20 credits a day; paid plans for more

ScrapeCreators credits (about $1.88 per 1,000 calls) plus Gemini usage for video

API keys

None, sign in with OAuth

ScrapeCreators, plus Gemini for video

Competitor discovery and competitive brief

✅

❌

Inline ad carousel

✅

❌

ChatGPT and claude.ai

✅ (ChatGPT app and Claude connector)

❌ (they need a public OAuth server)

Claude Desktop, Claude Code, Cursor

✅

✅

Setup and updates

None, managed for you

Python or Docker; git pull for updates

Best for

Marketers, agencies, teams

Developers who want to change the code

Need another platform? The other self-hosted servers: Facebook · Google · TikTok. Or get all four in one connection with hosted Proxy. Comparison and setup for all four: useproxy.dev/self-host.


Related MCP server: LinkedIn Ad Library MCP Server

Example Prompts

How many LinkedIn ads is 'Salesforce' running? What's their split across video, image and carousel?
Who is 'Datadog' targeting on LinkedIn? Break down the audience, seniority and locations across their ads.
Find LinkedIn ads mentioning 'AI agents' and tell me which offers they're pushing — demos, webinars or reports.
Do a deep comparison of the messaging between 'HubSpot' and 'Salesforce' on LinkedIn. Give it a nice forwardable summary.

Installation

Prerequisites

  • Python 3.12+

  • Anthropic Claude Desktop app (or Cursor)

  • Pip (Python package manager), install with python -m pip install

  • An API key for an ads data provider, set as SCRAPECREATORS_API_KEY (see configuration below)

  • A Google Gemini API key for video analysis (optional, only needed for video ads)

Prefer not to deal with API keys? See the Hosted Version above to skip setup entirely.

  1. Clone and run the install script

    git clone https://github.com/proxy-intell/linkedin-ads-library-mcp.git
    cd linkedin-ads-library-mcp
    
    # For macOS/Linux:
    ./install.sh
    
    # For Windows:
    install.bat
  2. Configure your API keys

    Edit the .env file that was created and add your API keys:

    • Set your ads data API key as SCRAPECREATORS_API_KEY

    • Get your Gemini API key at Google AI Studio (optional, for video analysis)

  3. Follow the displayed MCP configuration

    The install script will show you the exact configuration to add to Claude Desktop or Cursor.

Manual Install

If you prefer to install manually:

  1. Clone this repository

    git clone https://github.com/proxy-intell/linkedin-ads-library-mcp.git
    cd linkedin-ads-library-mcp
  2. Install dependencies

    pip install -r requirements.txt
  3. Configure API keys

    Copy the template and configure your API keys:

    cp .env.template .env
    # Then edit .env with your actual API keys

    To obtain API keys:

    • Set your ads data API key as SCRAPECREATORS_API_KEY in the .env file

    • Get a Google Gemini API key here (optional, for video analysis)

  4. Connect to the MCP server

    Add the MCP server configuration to your Claude Desktop or Cursor config:

    {
      "mcpServers": {
        "linkedin_ads_library": {
          "command": "/usr/local/opt/python@3.13/bin/python3",
          "args": [
            "{{PATH_TO_PROJECT}}/linkedin-ads-library-mcp/mcp_server.py"
          ]
        }
      }
    }

    Replace {{PATH_TO_PROJECT}} with the full path to where you cloned this repository.

    Note: API keys are automatically loaded from the .env file. Command line arguments are still supported and take priority over environment variables if provided.

    For Claude Desktop:

    Save this as claude_desktop_config.json in your Claude Desktop configuration directory at:

    ~/Library/Application Support/Claude/claude_desktop_config.json

    For Cursor:

    Save this as mcp.json in your Cursor configuration directory at:

    ~/.cursor/mcp.json
  5. Restart Claude Desktop / Cursor

    Open Claude Desktop and you should now see the LinkedIn Ads Library as an available integration.

    Or restart Cursor.


Deploy to the cloud

Run it as a remote MCP server so Cursor, Claude Code or Claude Desktop can reach it from anywhere.

Deploy to Render

  1. Click the button and enter your SCRAPECREATORS_API_KEY (and GEMINI_API_KEY for video). Render generates MCP_AUTH_TOKEN for you.

  2. Your endpoint is https://<your-service>.onrender.com/mcp/. Every request needs the header Authorization: Bearer <MCP_AUTH_TOKEN>.

  3. Claude Code: claude mcp add --transport http linkedin-ads https://<your-service>.onrender.com/mcp/ --header "Authorization: Bearer <MCP_AUTH_TOKEN>"

Any Docker host works the same way:

docker build -t linkedin-ads-library-mcp .
docker run -p 8000:8000 -e MCP_TRANSPORT=http -e MCP_AUTH_TOKEN=<long-random-string> -e SCRAPECREATORS_API_KEY=<key> linkedin-ads-library-mcp

The server refuses to start in HTTP mode without an MCP_AUTH_TOKEN of 16+ characters, so nobody else can spend your credits. Or skip all of this: hosted Proxy is already running.


Usage data

The server sends an anonymous ping to the maintainers on each tool call: the tool name, this repo's name, a call count and a random install ID stored in ~/.config/proxy-ads-mcp/. It never sends tool arguments, results, API keys or anything about you. Turn it off with PROXY_TELEMETRY=0 (or DO_NOT_TRACK=1). It tells us which tools people use so we know what to fix. Code: src/telemetry.py.

Every so often (the 25th call, then every 100th) a tool result includes a one-line tip about hosted Proxy.


Technical Details

  1. Claude sends requests to the Python MCP server

  2. The MCP server queries the ads data API for LinkedIn Ad Library data

  3. Data flows back through the chain to Claude

LinkedIn Ads

This server connects to LinkedIn's public Ad Library:

  • Three ways to search. company matches an advertiser name, keyword matches ad copy across advertisers, and company_id pins one exact organisation. Prefer company_id when you have it — name matching can pull in similarly named companies.

  • Targeting is the differentiator. LinkedIn publishes the audience an advertiser selected — language, location, and audience criteria like job seniority, function or company size. No other ad library exposes this, and it's the most useful field for B2B competitive work.

  • Ads run from people as well as pages. posterTitle and promotedBy tell you whether an ad is served from a company page or boosted from an employee's personal profile — a common founder-led B2B pattern.

  • Creative lives in three fields. image, video and carouselImages are populated depending on ad type, and carousel entries come back as either bare URLs or objects. The server normalises all of this into image_urls / video_url.

  • Detail lookups need a URL. The upstream detail endpoint takes a linkedin.com/ad-library/detail/... URL rather than an ID, so get_linkedin_ad_details accepts either and builds the URL for you.

Tips:

  • Search by company_id for exact advertiser matching; fall back to company name if you don't have it

  • Use keyword to research a topic or category rather than a single advertiser

  • Narrow with countries and start_date/end_date when an advertiser runs a lot of ads

Available MCP Tools

This MCP server provides tools for interacting with LinkedIn Ad Library objects:

Tool Name

Description

search_linkedin_ads

Searches the LinkedIn Ad Library by company, keyword or company ID, with country and date filters

get_linkedin_ad_details

Gets full detail for a specific ad — targeting, per-country impressions, creative and destination

analyze_ad_image

Downloads and analyzes ad images for visual elements, text, colors, and composition

analyze_ad_video

Downloads and analyzes ad videos using Gemini AI for comprehensive video insights

get_cache_stats

Gets statistics about cached media (images and videos) and storage usage

search_cached_media

Searches previously analyzed media by brand, colors, people, or media type

cleanup_media_cache

Cleans up old cached media files to free disk space


Troubleshooting

Common Issues

API Key Not Found Error:

  • Ensure your .env file is in the project root directory

  • If you don't have a .env file, copy it from the template: cp .env.template .env

  • Check that your API keys are correctly formatted without quotes

  • Verify the .env file contains SCRAPECREATORS_API_KEY=your_key_here

  • For video analysis, ensure GEMINI_API_KEY=your_key_here is also added

Search Returns No Ads:

  • Use the company name exactly as it appears on their LinkedIn page

  • Better still, search by company_id for an exact match

  • The advertiser may not have run ads in the period or countries you filtered to

Video Analysis Not Working:

  • Confirm you have a valid Google Gemini API key in your .env file

  • Pass ad_id alongside media_url so analysis caches per ad — LinkedIn CDN URLs carry expiry parameters that rotate

MCP Server Connection Issues:

  • Verify the path in your MCP configuration points to the correct location

  • Make sure you've installed all dependencies with pip install -r requirements.txt

  • Restart Claude Desktop/Cursor after configuration changes

For additional Claude Desktop integration troubleshooting, see the MCP documentation. The documentation includes helpful tips for checking logs and resolving common issues.


Tests

The response parsing has a self-check that runs without network access or API keys:

python3 test_parsing.py

FAQ

What is the easiest way to use the LinkedIn Ads Library MCP? The easiest way is the hosted version from Proxy (useproxy.dev). It requires no API keys, no installation, and no server — you connect it to ChatGPT, Claude, Cursor, or any MCP client and start querying immediately. You can start for free.

Do I need an API key to use this MCP? Only if you self-host. The hosted version at useproxy.dev handles all data access for you, so no ScrapeCreators or Gemini keys are needed. Self-hosting requires a SCRAPECREATORS_API_KEY (and a Gemini key for video analysis).

What can I get from LinkedIn that I can't get from the other ad libraries? Targeting. LinkedIn publishes the audience each advertiser selected — language, location, and criteria like job seniority, function and company size — which makes it the most useful ad library for B2B competitive research.

Which MCP clients does it work with? The hosted version works with ChatGPT, Claude (desktop, web and mobile), Cursor, Manus and any other MCP client. The self-hosted version works with local MCP clients such as Claude Desktop, Claude Code and Cursor, or as a remote server with a bearer token (see Deploy to the cloud).

Is there a free version? Yes — the hosted version from Proxy offers a free tier so you can start analyzing ads without any setup.

Should I self-host or use the hosted version? Use the hosted version if you just want fast, reliable access to LinkedIn Ad Library data with zero maintenance — this fits most users. Self-host only if you want to modify or extend the server code yourself.


Feedback

Your feedback will be massively appreciated. Please tell us which features on that list you like to see next or request entirely new ones.



License

This project is licensed under the MIT License.

License Python


Made with ❤️ by the team at Proxy.

Available Tools

7 tools
analyze_ad_imageA
Read-only

REQUIRED for analyzing images from LinkedIn ads. Download and analyze ad images (single image creatives, carousel cards and document/thumbnail covers) to extract visual elements, text content, colors, people, brand elements, and composition details. This tool should be used for EVERY image URL returned by search_linkedin_ads when doing comprehensive analysis. Uses intelligent caching so multiple image analysis calls are efficient and cost-free.

Inputs: media_url (required), ad_id, brand_name.

analyze_ad_videoA
Read-only

REQUIRED for analyzing video ads from LinkedIn. Downloads and analyzes ad videos using Gemini's video understanding to extract the hook, scene-by-scene storytelling, on-screen text, voiceover, sound-off readability and B2B offer positioning. Pass ad_id alongside media_url so results cache per ad rather than per (expiring) CDN URL. Uses intelligent caching for efficiency.

Inputs: media_url (required), ad_id, brand_name.

cleanup_media_cacheA

REQUIRED for cleaning up old cached media files (images and videos) and freeing disk space. Use this tool when users want to remove old cached media, clean up storage space, or when cache becomes too large. Essential for cache maintenance and storage management.

Inputs: max_age_days.

get_cache_statsA
Read-only

REQUIRED for checking media cache status and storage usage. Use this tool when users ask about cache statistics, storage space used by cached media (images and videos), or how many files have been analyzed and cached. Essential for cache management and monitoring.

Inputs: no named parameters.

get_linkedin_ad_detailsA
Read-only

Get detailed information about a specific LinkedIn ad including full targeting (language, location, audience), per-country impression breakdown, creative and destination URL. Use this with an ad id from search_linkedin_ads, or a linkedin.com/ad-library/detail/ URL. Essential for understanding who an advertiser is targeting and extracting media URLs for visual analysis.

Inputs: ad_id (required).

search_cached_mediaA
Read-only

REQUIRED for finding previously analyzed ad media (images and videos) in cache. Use this tool when users want to search for cached media by brand name, find media with people, search by colors, or filter by media type. Essential for retrieving past analysis results without re-downloading media.

Inputs: limit, brand_name, has_people, media_type, +1 more.

search_linkedin_adsA
Read-only

Search LinkedIn's Ad Library for the ads a company is running. Search by company name, by keyword across ad copy, or by LinkedIn company ID (most precise). Supports country and date-range filters. Returns headline, description, CTA, destination URL, targeting, impressions and media URLs. For complete analysis of visual elements, colors, design, or creative content, you MUST also use analyze_ad_image or analyze_ad_video on the media returned by each ad.

Inputs: limit, company, keyword, end_date, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: live ad search, ad details, image analysis, video analysis, and cache management operations. There is no meaningful overlap between searching LinkedIn ads and searching cached media, and the analysis tools are cleanly separated by media type.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., search_linkedin_ads, analyze_ad_image, cleanup_media_cache). Verbs are descriptive and specific, with no mixing of conventions or vague names.

    Tool Count5/5

    With 7 tools, the server is well-scoped for its purpose: searching and analyzing LinkedIn ads plus managing the media cache. Each tool serves a distinct function without redundancy or bloat.

    Completeness5/5

    The tool surface covers the full workflow: searching ads, retrieving detailed targeting/creative info, analyzing images and videos, and managing the cache that stores analyzed media. No obvious gaps or dead ends exist; cache stats and cleanup ensure lifecycle coverage.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers