flin-linkedin-ads-mcp
This is a read-only MCP server for exploring LinkedIn Ads data and public LinkedIn ad-library content.
Check connection/auth status, start or reconnect LinkedIn login, and verify live access via ad-account listing.
List/fetch ad accounts, campaign groups, campaigns, and creatives.
Read insights/analytics with pivots, date ranges, filters, sorting, and metrics.
Retrieve creative image/video preview media inline or as local files where authorized.
Resolve share/ugcPost content and image URLs via Posts/Images APIs when permissions allow.
Read private company-level account intelligence if enabled for the app.
Search public LinkedIn Ad Library ads by keyword, advertiser, payer, country, dates, targeting categories, and impressions.
Search organic LinkedIn posts marked as brand partnerships.
Perform no create/update/delete, pause/resume, or generic proxy operations; auth tools only manage local credentials.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@flin-linkedin-ads-mcp list my LinkedIn ad accounts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
flin-linkedin-ads-mcp
flin-linkedin-ads-mcp ist ein strikt read-only MCP Server für LinkedIn Ads.
Er ist dafür gebaut, direkt in Claude über MCP eingebunden und getestet zu werden.
Start mit Claude Desktop auf Apple Silicon (M1 oder neuer)
Desktop-Paket herunterladen und mit Claude Desktop öffnen. Alternativ: Einstellungen → Desktop-App → Erweiterungen verwalten → Erweiterte Einstellungen → Erweiterung installieren.
LinkedIn Client-ID und Client-Secret der App aus eurem Passwortmanager in die beiden Einstellungsfelder eintragen. Diese Werte erhältst du vom zuständigen Administrator. Keine Secrets in den Chat schreiben.
Persönlich anmelden: „Verbinde mich mit LinkedIn Ads“ schreiben und den Link von
linkedin_loginauf demselben Mac öffnen. Mit dem eigenen LinkedIn-Konto anmelden; dieses braucht Zugriff auf die Werbekonten. Die App benötigtr_adsundr_ads_reportingsowie die registrierte Rückleitungsadressehttp://localhost:9876/callback.Verbindung prüfen:
connection_statuszeigt die laufende Serverversion und den lokalen Zustand. Danach „Zeige mir meine LinkedIn-Werbekonten“ (list_ad_accounts) ausführen. Erst dessen erfolgreiche Antwort bestätigt den Live-Zugriff; ein vorhandener Token allein tut das nicht.
Aktuelles Claude Desktop mit MCPB-0.4-/UV-Unterstützung und Internetzugang erforderlich. Intel-Macs bleiben unterstützt; die lokale Paketprüfung erfolgt auf Apple Silicon. Python-Installationen auf anderen unterstützten Systemen bleiben möglich.
Updates: Claude vollständig beenden und neu öffnen. Die Erweiterung lädt stabile
Serverversionen im unterstützten Bereich 0.x von PyPI, ohne laufende Sitzungen zu ändern.
App-Einstellungen und persönliche Tokens bleiben erhalten. Die Erweiterungsversion in
Claude bezeichnet den Starter; connection_status.server_version (im Antwortfeld data)
bezeichnet den tatsächlich laufenden Server. Für Änderungen am Starter kann ein einmaliger
neuer Paketimport nötig sein. Details und Fallback: SUPPORT.md.
Installation und Updates · Datenschutz ·
Sicherheit · Hilfe. Der bisherige Downloadname
flin-linkedin-ads-mcp-macos.mcpb bleibt gültig. Releases enthalten zusätzlich einen
versionierten Paketnamen und SHA256SUMS.
Related MCP server: linkedin-campaign-manager-mcp
Features
Read-only Zugriff auf LinkedIn Ads Daten
Ad Accounts lesen
Campaign Groups lesen
Campaigns lesen
Creatives lesen
Bilder und Video-Vorschaubilder im Chat ausgeben und lokal herunterladen (
get_creative_media)Share-Content lesen (
get_share_content, best effort für Bild-URLs)Insights/Analytics lesen
Company Intelligence lesen (
/accountIntelligence, private API Access nötig)Öffentliche Anzeigen in der LinkedIn Ad Library suchen (
search_ad_library)Als Markenpartnerschaft gekennzeichnete Beiträge suchen (
search_brand_partnerships)Direkter LinkedIn-Login und Reconnect über
linkedin_loginAutomatische Token-Erneuerung, falls LinkedIn einen Refresh-Token ausstellt
Keine Schreiboperationen an Werbekonten oder Kampagnen in
v0.x
Neu in v0.3.0
Neues Tool
get_creative_media: Bilder und Video-Vorschaubilder direkt im Chat anzeigen und als lokale Dateien für den Dashboard-Import speichern.Vollständige MP4-Videos herunterladen, sofern der Zugang die Posts- und Videos-API erlaubt.
Konfigurierbarer Speicherort über
LINKEDIN_MEDIA_DIR, begrenzte Dateigrössen und geprüfte LinkedIn-CDN-Downloads ohne Weitergabe des API-Tokens.
Neu in v0.2.0
Ad-Library-Suche und Markenpartnerschafts-Suche mit Filtern und Seitennavigation.
Anzeigenbilder über Creative-Metadaten ab API-Version
202610, auch ohne Posts-Zugriff.Aktuelle Posts-/Images-Abfragen statt des alten Share-Endpunkts.
API-Version
202610als neuer Standard und verständliche Hinweise bei inaktiven Versionen.
Bestehende Installationen mit explizitem LINKEDIN_API_VERSION müssen diesen Wert auf
202610 setzen, um die neue Bildauflösung zu nutzen. Anschliessend den MCP-Client neu starten.
Die Ad Library benötigt eine separate Produktfreischaltung der LinkedIn App. Die Bildadressen
aus get_creative bleiben externe URLs. get_creative_media kann Dateien separat abrufen;
für Dashboards ist anschliessend deren unterstützter Datei-/Asset-Import nötig.
Scope v0.x (strict read-only)
Kein Create/Update/Delete
Kein Pause/Resume
Kein generischer Proxy-Endpunkt
Authentifizierungs-Tools speichern ausschliesslich lokale Zugangsdaten; Ads-Daten bleiben read-only
Entwicklerinstallation und manuelle Konfiguration
Variante A: Lokal aus diesem Repo (empfohlen zum Entwickeln)
In Claude:
SettingsöffnenDeveloperöffnenMCP Config bearbeiten
Diesen Server eintragen:
{
"mcpServers": {
"flin-linkedin-ads-mcp-local": {
"command": "uv",
"args": [
"run",
"--directory",
"/ABSOLUTER/PFAD/flin-linkedin-ads-mcp",
"flin-linkedin-ads-mcp"
],
"env": {
"LINKEDIN_CLIENT_ID": "DEINE_APP_CLIENT_ID",
"LINKEDIN_CLIENT_SECRET": "DEIN_APP_CLIENT_SECRET",
"LINKEDIN_REDIRECT_URI": "http://localhost:9876/callback",
"LINKEDIN_API_VERSION": "202610",
"LINKEDIN_RESTLI_PROTOCOL_VERSION": "2.0.0"
}
}
}
}In der LinkedIn Developer App unter Auth zuerst exakt http://localhost:9876/callback
als Redirect URL eintragen. Danach Claude neu starten und linkedin_login aufrufen.
Den zurückgegebenen Link auf demselben Computer im Browser öffnen und bei LinkedIn anmelden.
Anschliessend linkedin_login_status und list_ad_accounts aufrufen.
Die App braucht die Berechtigungen r_ads und r_ads_reporting.
Ein bereits vorhandener LINKEDIN_ACCESS_TOKEN funktioniert weiterhin. Nach einem Login
hat der gespeicherte OAuth-Token Vorrang vor einem alten Token aus der Konfiguration.
Variante B: Via uvx (wenn Paket publiziert ist)
{
"mcpServers": {
"flin-linkedin-ads-mcp": {
"command": "uvx",
"args": ["--refresh", "flin-linkedin-ads-mcp"],
"env": {
"LINKEDIN_CLIENT_ID": "DEINE_APP_CLIENT_ID",
"LINKEDIN_CLIENT_SECRET": "DEIN_APP_CLIENT_SECRET",
"LINKEDIN_REDIRECT_URI": "http://localhost:9876/callback",
"LINKEDIN_API_VERSION": "202610",
"LINKEDIN_RESTLI_PROTOCOL_VERSION": "2.0.0"
}
}
}
}Verbindungstest bei manueller Installation
Nach dem Restart in Claude diese Calls testen:
linkedin_loginund den zurückgegebenen Link öffnenlinkedin_login_status(nach erfolgreichem Login:token_available)list_ad_accountslist_campaignsget_insightsmitpivot=campaign
Wenn list_campaigns eine Auswahl zurückgibt, den Call mit einem vorgeschlagenen ad_account_id wiederholen.
Hinweis zu get_insights:
Der MCP nutzt den LinkedIn
analyticsFinder mit Single-Pivot.Implementierung ist auf die Dokumentation
view=li-lms-2026-03ausgerichtet.date_fromist Pflicht (LinkedInadAnalyticserwartetdateRange).Unterstützte
fieldsfolgen der Metrics-Tabelle aus der offiziellen Reporting-Schema-Doku (max. 20 Felder pro Request).Der Server nutzt intern
pivot.value/timeGranularity.valueund hat zusätzlich einen Fallback auf Legacy-Parameternamen für bessere API-Kompatibilität.Neuere Video/Event-Felder sind enthalten, z. B.
videoWatchTime,averageVideoWatchTime,eventViews,eventWatchTime,averageEventWatchTime.
Beispiel für einen stabilen Test-Call:
{
"ad_account_id": "123456789",
"date_from": "2025-08-01",
"date_to": "2025-12-31",
"fields": [
"impressions",
"clicks",
"costInLocalCurrency",
"dateRange"
],
"pivot": "account",
"time_granularity": "MONTHLY"
}LinkedIn Ad Library
Voraussetzung ist das freigeschaltete Produkt LinkedIn Ad Library auf der App,
die den verwendeten Mitgliedstoken ausgestellt hat. Ein vorhandener gültiger
OAuth-Mitgliedstoken kann weiterverwendet werden; es ist kein zusätzlicher OAuth-Scope
erforderlich. Beide Tools funktionieren ohne ad_account_id und ohne Zugriff auf
das Werbekonto des gesuchten Unternehmens. Der bestehende Ads-Login bleibt unverändert.
search_ad_library
Sucht über GET /rest/adLibrary?q=criteria nach öffentlichen Anzeigen, auch anderer Unternehmen.
keyword: Suchbegriffe im Anzeigeninhalt; mehrere Wörter werden mit UND verknüpft.advertiser: Name des werbenden Unternehmens.payer_name: Name der zahlenden Person oder Organisation.countries: zweistellige Ländercodes, z. B.["CH", "DE", "AT"].date_fromunddate_to: gemeinsam im FormatYYYY-MM-DD; Start inklusive, Ende exklusiv. Ohne diese Angaben nutzt LinkedIn nur heute minus 2 Tage bis heute minus 1 Tag, nicht das gesamte Archiv.included_targeting_categories/excluded_targeting_categories: Targeting-Kategorien, z. B.["COMPANY", "JOB"]; die verfügbaren Werte stehen im Tool-Schema.impressions_fromundimpressions_to: gemeinsam als Impression-Bereich;1000000bis0steht für die offene oberste Klasse ab einer Million.sort_order:ASCENDINGoderDESCENDING, sortiert nach Erstellungszeit der Anzeige.page_start: Offset ab0;page_size:1bis25, Standard25.
Beispiel für search_ad_library:
{
"advertiser": "Microsoft",
"countries": ["DE", "AT"],
"date_from": "2026-10-01",
"date_to": "2026-10-29",
"page_size": 25
}Die Antwort behält die API-Felder unverändert bei: adUrl, details mit Inserent,
Anzeigenformat, verfügbaren Targeting- und Impression-Daten sowie isRestricted und
restrictionDetails. Umfang und Verfügbarkeit hängen von der Anzeige und Region ab;
zusätzliche Transparenzdaten betreffen insbesondere EU-Anzeigen. Die API liefert
Vorschaulinks, keine heruntergeladenen Anzeigenbilder oder vollständigen Anzeigentexte
und keine Klick-, Kosten- oder Conversion-Berichte. Redaktionen bei eingeschränkten
Anzeigen bleiben erhalten. Anzeigen bleiben üblicherweise ein Jahr nach ihrer letzten
Impression in der Bibliothek.
search_brand_partnerships
Sucht über GET /rest/paidEndorsementPosts?q=searchCriteria nach organischen Beiträgen,
die Creators als Markenpartnerschaft gekennzeichnet haben. Die Antwort enthält postUrl.
keyword: Pflicht; mehrere Wörter werden mit UND verknüpft.date_range: optionalPAST_24H,PAST_WEEKoderPAST_MONTH; ohne Filter sind verfügbare Beiträge bis maximal ein Jahr nach Veröffentlichung durchsuchbar.page_startundpage_size: wie bei der Anzeigensuche; der MCP begrenzt beide Tools auf höchstens 25 Ergebnisse pro Aufruf.
{
"keyword": "technology",
"date_range": "PAST_MONTH",
"page_size": 10
}Weitere Seiten und Zugriffsfehler
Beide Tools liefern paging.next_start, paging.has_next und, sofern von LinkedIn
geliefert, paging.total. Für die nächste Seite dieselben Filter mit
page_start=paging.next_start erneut aufrufen. paging.next_after enthält denselben
Offset als String zur Kompatibilität mit dem bestehenden Antwortformat. Fehlen die
Paging-Angaben, kann eine volle Seite einen abschliessenden leeren Aufruf erfordern.
Bei 403 / ACCESS_DENIED prüfen, ob die MCP-Zugangsdaten zur freigeschalteten App
gehören und das Produkt im Developer Portal aktiv ist. Ein gültiger Token oder der
Status token_available allein bestätigt den Ad-Library-Zugriff nicht. Bei Bedarf
über linkedin_login neu verbinden und die Suche wiederholen; eine fehlende
Produktfreischaltung wird durch einen neuen Login nicht behoben.
Offizielle Referenzen: Zugang und Authentifizierung, Anzeigen-Schema, Markenpartnerschaften-Schema.
get_insights Parameter (2026-03)
Wichtigste Parameter:
pivot: z. B.account,campaign_group,campaign,creative,member_company_size,member_industry,member_seniority,member_job_title,member_job_function,member_country_v2,member_region_v2,member_company,member_county,share,company,conversiontime_granularity:DAILY,MONTHLY,ALL,YEARLYfields: Liste aus der offiziellen Metrics-Tabelle, maximal 20 Einträge, case-sensitiveKompatibilitätsfelder:
pivotValue→pivotValues,clickThroughRate(berechnet alsclicks / impressions),costPerClick(berechnet alscostInLocalCurrency / clicks)
date_from:YYYY-MM-DD(Pflicht)date_to: optional,YYYY-MM-DD
Facets/Filter:
ad_account_id(ein Konto) oderaccount_ids(mehrere Konten)optional zusätzlich:
campaign_ids,campaign_group_ids,creative_ids,share_ids,company_idsoptional:
campaign_type,objective_typeoptional Sortierung:
sort_by_field+sort_order(müssen zusammen angegeben werden)
Kompatibilität:
entity_idsbleibt für Backward-Kompatibilität erhalten (z. B. beipivot=campaign).
list_creatives / get_creative Bild-URL (optional)
Für Creative-Calls kann optional das Derived-Field imageUrl in fields angefordert werden.
Ab API-Version
202610wirdimageUrlbevorzugt ausmetadata.assetURLder einzelnen Creative-Abfrage gelesen. Dafür ist kein Zugriff auf die Posts-API nötig.get_creativefordert das Metadatum im selben Aufruf an;list_creativesmacht nur bei angefordertemimageUrlodermetadataeine zusätzliche Abfrage je Creative (doppelte IDs werden pro Seite zwischengespeichert). Ohne diese Felder bleibt es bei einer Listenabfrage.metadatakann zusätzlich infieldsangefordert werden und enthält je nach Format u. a.adHeadline,adIntroductionText,adFormat,assetURLundlandingPage. Auf älteren API-Versionen wird eine ausdrückliche Anfrage nachmetadatamit einem Konfigurationshinweis abgelehnt.Fehlt eine Bildadresse in den Metadaten, wird der Creative-
contentgeprüft.Falls dort keine Bild-URL enthalten ist und eine
content.referenceaufurn:li:adDirectSponsoredContent:*zeigt, versucht der MCP zusätzlich eine Auflösung überadDirectSponsoredContents/{urn}.Falls dort keine Bild-URL enthalten ist und eine Share-/UGC-Post-Referenz vorhanden ist, versucht der MCP zusätzlich eine Auflösung über die aktuelle Posts-API und bei Bild-URNs über die Images-API. Auch verschachtelte Referenzen in
standardUpdateAdundvideoAdwerden erkannt.Wenn keine Bild-URL auflösbar ist, ist
imageUrlnull.
Beispiel:
{
"ad_account_id": "123456789",
"id": "urn:li:sponsoredCreative:987654321",
"fields": ["id", "name", "imageUrl"]
}list_account_intelligence (202603)
Neues Tool:
list_account_intelligence
Dieser Endpunkt nutzt GET /rest/accountIntelligence?q=account und ist laut LinkedIn private API (zusätzliche Freischaltung erforderlich).
Wichtige Parameter:
ad_account_id(oder Auto-Resolve bei genau einem Account)lookback_window:LAST_7_DAYS,LAST_30_DAYS,LAST_60_DAYS,LAST_90_DAYSoptional:
ad_segment_ids,campaign_idoptional:
skip_company_decorationoptional:
page_start,page_size(max. 1000)
Wichtige Response-Felder:
companyName,engagementLevelpaidImpressions,paidClicks,paidEngagements,paidLeadspaidQualifiedLeads,conversions(ab API-Version202603)organicImpressions,organicEngagements
Beispiel:
{
"ad_account_id": "123456789",
"lookback_window": "LAST_30_DAYS",
"page_size": 100
}get_share_content (best effort)
Neues Tool:
get_share_content
Wichtige Parameter:
share_urn(Pflicht, Formaturn:li:share:<id>oderurn:li:ugcPost:<id>)include_raw(optional,truegibt zusätzlich das rohe API-Payload zurück)
Response enthält u. a.:
share_urn,source_endpoint(posts)post_url(LinkedIn Feed URL)textimage_url(erstes gefundenes Bild odernull)image_urls,thumbnail_urls
Beispiel:
{
"share_urn": "urn:li:share:1234567890123456789",
"include_raw": false
}Anzeigenbilder und Dashboard-Einbettung
Für Anzeigenbilder bevorzugt get_creative / list_creatives mit fields: ["id", "imageUrl", "metadata"]
und LINKEDIN_API_VERSION=202610 verwenden. Eine explizit auf 202603 oder älter gesetzte
MCP-Konfiguration überschreibt weiterhin den neuen Default: dort den Wert ändern und den
Server neu starten. Ein Paket-Update allein ändert diese Konfiguration nicht.
get_share_content verwendet die aktuelle Posts-API. Der alte /shares-Endpunkt wird
nicht mehr aufgerufen. Ein 403 an /posts oder /images bedeutet fehlende Berechtigungen
für diese APIs, auch wenn die Ads-Abfragen funktionieren. Der Connector fordert dafür keine
zusätzlichen Schreibberechtigungen an. Der Creative-Metadatenweg funktioniert unabhängig
vom Posts-Zugriff. Ein 426 enthält nun einen Hinweis auf die konfigurierte Version und
gegebenenfalls die nötige Endpoint-Migration, statt wie ein Login-Fehler behandelt zu werden.
Die Bildadressen sind externe, möglicherweise zeitlich begrenzte LinkedIn-URLs. Wenn ein
Dashboard externe Bilder blockiert, löst eine funktionierende URL diese Einschränkung
nicht: Für eine Einbettung müssen die ausgewählten Bilder über den vom Dashboard erlaubten
Import-/Asset-Workflow bereitgestellt werden. Der Connector exportiert oder lädt mit diesen
URL-Tools keine Bilddateien herunter. Für einen Dateiabruf gibt es get_creative_media;
Dashboard-Sicherheitsregeln bleiben unverändert.
LinkedIn-Vorschaulinks bleiben eine mögliche Alternative. Eine assetURL kann je nach
Anzeigenformat auch ein anderes Medium sein; erkennbare Video-/PDF-URLs werden nicht als
imageUrl ausgegeben.
Referenzen: Creative-Metadaten, Posts-API, Images-API.
get_creative_media: Chat-Vorschau und Dateien für Dashboards
Das Tool lädt das Medium einer zugänglichen Anzeige herunter. Standardmässig liefert es
ein natives MCP-Bild für den Chat und speichert dieselbe Datei lokal. Bei einer Videoanzeige
ist kind: "preview" das Vorschaubild, nicht die Videodatei. Die tatsächliche Darstellung
des Bildes hängt vom MCP-Client ab.
{
"ad_account_id": "123456789",
"id": "urn:li:sponsoredCreative:987654321",
"kind": "preview",
"output": "both"
}kind:preview(Standard) für Bilder/Vorschaubilder,videofür die vollständige MP4.output:inlinefür ein MCP-Bild ohne lokale Datei,filefür eine lokale Datei,both(Standard) für beides. Videos unterstützenfileundboth; beide liefern eine Datei und einen Dateiverweis, keinen nativen Video-Block.Die Textantwort enthält
mime_type,size_bytes,sha256und bei Dateiausgabelocal_path/file_uri. Bilddaten werden separat als MCPImageContentausgegeben, nicht als Base64 im Antworttext.Speicherort:
~/.cache/flin-linkedin-ads-mcp/media, konfigurierbar mitLINKEDIN_MEDIA_DIR. Dateien erhalten inhaltsbasierte Namen und private Dateirechte. Der lokale Bestand wird nicht automatisch gelöscht; nicht mehr benötigte Dateien können dort entfernt werden.Die Dateien liegen auf dem Rechner des MCP-Servers. Für ein Dashboard müssen sie über dessen unterstützten Asset-Import übernommen werden. Ein lokaler Pfad ist keine öffentliche Bildadresse und kein automatischer Upload; entfernte Clients brauchen einen Datei-Transfer.
Unterstützt: JPEG, PNG, GIF, WebP bis 5 MiB; MP4 bis 100 MiB. Dateityp und Dateisignatur werden geprüft. Downloads und Weiterleitungen sind auf HTTPS-LinkedIn-CDN-Adressen beschränkt; der API-Token wird nicht an den CDN-Server gesendet.
Vollständige Videos werden über den referenzierten Post und die Videos-API aufgelöst. Dafür sind die jeweiligen Leseberechtigungen nötig. Ein
403nenntkind: "preview"als Alternative. Das Tool gibt niemals ein JPEG als erfolgreich heruntergeladenes Video aus.Medienadressen können ablaufen; jeder Aufruf löst sie erneut auf. Bei einem Downloadfehler den Aufruf wiederholen. Der Connector verändert weiterhin keine LinkedIn-Ads-Daten.
Nach Installation des aktualisierten Codes den MCP-Client neu starten, damit das neue Tool sichtbar wird. Ein bereits installiertes veröffentlichtes Paket erhält lokale Änderungen nicht automatisch.
Referenzen: Videos-API, MCP-Bilder und Dateiverweise.
Troubleshooting get_insights
Bei ILLEGAL_ARGUMENT oder RESOURCE_NOT_FOUND bitte prüfen:
Feldnamen sind exakt korrekt (
clicksstattclick,impressionsstattimpression).Maximal 20
fields.Mindestens ein gültiger Facet-Filter (
ad_account_id/account_idsoder andere Facets).IDs im korrekten Format (Account/Campaign/Campaign Group/Creative numerisch oder URN;
share_idsundcompany_idsals URN).Datum im Format
YYYY-MM-DD.date_fromist gesetzt (ohnedateRangeantwortet LinkedIn oft mitILLEGAL_ARGUMENT).pivotist einer der dokumentierten Werte (siehe oben).
Schneller API-Gegencheck (ohne MCP) für das Token:
curl -i 'https://api.linkedin.com/rest/adAccounts?q=search&pageSize=1' \
-H 'Authorization: Bearer DEIN_ACCESS_TOKEN' \
-H 'Linkedin-Version: 202603' \
-H 'X-Restli-Protocol-Version: 2.0.0'Direkt anmelden und neu verbinden
Die Anmeldung ist für einen lokalen stdio-MCP-Server mit einem Benutzer vorgesehen. Browser und Server müssen auf demselben Computer laufen. Dies ist keine OAuth-Anmeldung für einen gemeinsam genutzten Remote-/HTTP-Connector.
Einmalige Einrichtung:
In der LinkedIn Developer App den Marketing-/Advertising-Zugang mit
r_adsundr_ads_reportingfreischalten. Der anmeldende Benutzer braucht Zugriff auf das Werbekonto.Unter Auth die Redirect URL
http://localhost:9876/callbackregistrieren.LINKEDIN_CLIENT_IDundLINKEDIN_CLIENT_SECRETin der MCP-Konfiguration hinterlegen (siehe Beispiel oben). Secrets gehören nicht in den Chat.MCP-Client einmal neu starten, damit er die neue Konfiguration und Tools lädt.
Danach reicht im Chat die Bitte „LinkedIn Ads neu verbinden“:
linkedin_loginliefertauthorization_url. Den Link im lokalen Browser öffnen.Der Server nimmt die Rückleitung automatisch entgegen und speichert den Token.
linkedin_login_statuszeigt den lokalen Status;token_availablebestätigt noch keine Kontoberechtigungen. Mitlist_ad_accountsden echten API-Zugriff prüfen.Anschliessend den ursprünglichen Call wiederholen, zum Beispiel
get_ad_accountmit{"id":"123456789"}. Kein weiterer Neustart und kein Token-Kopieren nötig.
Login-Links gelten zehn Minuten. Ein erneuter Aufruf während eines offenen Logins
liefert denselben Link. Abbruch, Ablauf oder ein Fehler lässt sich über den Status abfragen;
anschliessend kann ein neuer Login gestartet werden. Bei einem belegten Callback-Port
entweder den anderen Server schliessen oder LINKEDIN_REDIRECT_URI auf einen freien Port
ändern und dieselbe URL in der LinkedIn App registrieren.
Token-Speicherung und Erneuerung
Standard: ~/.config/flin-linkedin-ads-mcp/tokens.json (über LINKEDIN_TOKEN_FILE änderbar).
Die Datei enthält sensible Zugangsdaten, wird atomar mit Dateirechten 0600 geschrieben
und sollte ausserhalb des Repositories bleiben. Sie ist keine verschlüsselte Schlüsselablage.
Für getrennte Benutzer/Verbindungen jeweils eine eigene Datei und einen eigenen Callback-Port
verwenden. Ein gespeicherter Token wird nur für die zugehörige Client ID geladen.
Ein gespeicherter Login hat Vorrang vor LINKEDIN_ACCESS_TOKEN. Die Tokens werden beim
Serverstart geladen und nach erfolgreichem Login sofort im laufenden Server verwendet.
Token, Client Secret und Authorization Code erscheinen nicht in den Auth-Tool-Antworten
oder Callback-Logs. linkedin_login_status gibt nur Status und Ablaufzeitpunkte zurück.
Falls LinkedIn einen Refresh-Token ausstellt, erneuert der Server den Access-Token kurz
vor Ablauf bei der nächsten API-Abfrage sowie einmal nach einer 401-Antwort.
Abgelaufene/widerrufene Refresh-Tokens führen zurück zu linkedin_login.
Programmatic Refresh hängt von der Freischaltung der LinkedIn App ab;
offline_access wird nicht angefordert. Siehe
LinkedIn Programmatic Refresh Tokens.
401/403 diagnostizieren
401/EXPIRED_ACCESS_TOKEN:linkedin_loginaufrufen und den Link öffnen.Login meldet fehlende Konfiguration: Client ID und Client Secret einmalig hinterlegen.
403: App-Berechtigungen und Rolle des angemeldeten Benutzers im Werbekonto prüfen.Der Server kann auch ohne Token starten, damit die Login-/Status-Tools verfügbar sind.
Environment Variablen
Für direkten Login:
LINKEDIN_CLIENT_IDundLINKEDIN_CLIENT_SECRET(immer zusammen setzen)LINKEDIN_REDIRECT_URI(Default:http://localhost:9876/callback; HTTP,localhostoder127.0.0.1, expliziter Port und Pfad; muss exakt in der App registriert sein)LINKEDIN_TOKEN_FILE(Default:~/.config/flin-linkedin-ads-mcp/tokens.json)
Alternativ bleibt LINKEDIN_ACCESS_TOKEN als fest hinterlegter Token unterstützt.
Ohne OAuth-App-Konfiguration kann dieser Token nicht automatisch erneuert werden.
Weitere Optionen:
LINKEDIN_API_VERSION(Default:202610)LINKEDIN_RESTLI_PROTOCOL_VERSION(Default:2.0.0)LINKEDIN_TIMEOUT_SECONDS(Default:30)LINKEDIN_MAX_RETRIES(Default:3)
Lokale Entwicklung
cd /ABSOLUTER/PFAD/flin-linkedin-ads-mcp
python -m pip install -e ".[dev]"
pytest -q
ruff check .
mypy srcSicherheit (wichtig)
Niemals
LINKEDIN_ACCESS_TOKENoder OAuth Secrets ins Repo committen.envist bereits in.gitignoreApp-Zugangsdaten nur über MCP
envoder lokale Shell-Umgebung setzen; OAuth-Tokens werden lokal gespeichertVor jedem Push prüfen:
git status
git diff -- .envWenn eine Datei mit Secrets auftaucht: Commit abbrechen und Secrets rotieren.
GitHub Actions & Release (PyPI und GitHub)
Dieses Repo enthält:
CI Workflow:
.github/workflows/ci.ymlRelease Workflow:
.github/workflows/release.yml
Der Release-Workflow macht bei v* Tags:
Lint, Typecheck, Tests und Schwachstellenabgleich mit festgeschriebenen Abhängigkeiten
Python- und MCPB-Build,
twine check, Manifestprüfung und MCP-StarttestTrusted Publishing zu PyPI (Environment
pypi) mit anschliessender Prüfung aller Datei-HashesErst danach GitHub Release mit Python-Paketen, MCPB-Aliasen, versioniertem MCPB und Prüfsummen
Node-20-Deprecation-Warnungen sind abgefangen durch:
aktuelle Actions-Majors (
checkout@v6,setup-python@v6)FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: truein beiden Workflows
Jedes Release muss auf PyPI und GitHub verfügbar sein. Der portable Release-Build läuft auf Linux; die ergänzenden Mac-Tests laufen separat in CI und blockieren PyPI nicht durch eine Mac-Runner-Warteschlange. Ein Release gilt erst nach erfolgreicher Prüfung beider Veröffentlichungen als abgeschlossen.
Eine unterbrochene Veröffentlichung kann über Actions → Release → Run workflow mit
release_tag (z. B. v0.3.1) nachgeholt werden. Der Workflow verwendet den unveränderten
Tag, überspringt bereits auf PyPI vorhandene Dateien nur mit anschliessender Hash-Prüfung
und ersetzt keine bestehenden GitHub-Dateien. Abweichende Dateiinhalte führen zu einem Fehler. Bei identischen Quellarchiv-Inhalten
und lediglich anderer Archivierung werden die bereits veröffentlichten Originalbytes
weiterverwendet. Veröffentlichten Code nicht nachträglich unter demselben Tag ändern.
PyPI Trusted Publisher einmalig einrichten
PyPI Project:
flin-linkedin-ads-mcpOwner:
flin-agencyRepository:
flin-linkedin-ads-mcpWorkflow:
release.ymlEnvironment:
pypi
Release auslösen
git add -A
git commit -m "release: v0.1.0"
git tag v0.1.0
git push origin main --tagsOffizielle Referenzen
LinkedIn OAuth Overview:
Authorization Code Flow (native clients):
Reporting (Ad Analytics):
Reporting Schema (Metrics + Query Parameters):
Company Intelligence API:
Programmatic Refresh Tokens:
Available Tools
17 toolsconnection_statusA
Report running server version, local configuration and authentication status. No network, browser, refresh or writes. Token presence means unknown, not authenticated. live_access is not_checked; use list_ad_accounts for an explicit live check.
Inputs: no named parameters.
get_ad_accountB
Fetch one LinkedIn ad account by id
Inputs: id (required), fields.
get_campaignC
Fetch one campaign by id
Inputs: id (required), fields, ad_account_id.
get_campaign_groupB
Fetch one campaign group by id
Inputs: id (required), fields, ad_account_id.
get_creativeB
Fetch one creative by id. Request fields imageUrl or metadata for the visual asset URL via CreativeMetadata on API 202610+, without needing Posts access. Image URLs are external and may expire.
Inputs: id (required), fields, ad_account_id.
get_creative_mediaA
Download an authorized creative's image or video thumbnail (kind=preview), or full MP4 (kind=video, requires Posts and Videos API access). output=inline returns a native MCP image; file saves locally; both does both for previews and saves a file for videos. Defaults: preview, both. Limits: images 5 MiB, videos 100 MiB. Files are on the MCP server's computer, not hosted URLs; use the dashboard's supported asset import. Rendering depends on the client. Downloads write only local files, never Ads data.
Inputs: id (required), kind, output, ad_account_id.
get_insightsC
Fetch LinkedIn ads analytics
Inputs: date_from (required), pivot, fields, date_to, +13 more.
linkedin_loginA
Connect or reconnect LinkedIn Ads, including after EXPIRED_ACCESS_TOKEN/401. Returns a login URL to open in a browser on the MCP server's computer. Saves credentials locally after consent. Requires configured LinkedIn app client ID and secret. Never ask for tokens, passwords or secrets in chat.
Inputs: no named parameters.
linkedin_login_statusA
Check local LinkedIn login progress and token expiry without exposing credentials. After login, use list_ad_accounts to verify API access.
Inputs: no named parameters.
list_account_intelligenceC
List company-level account intelligence rows (private LinkedIn API access required)
Inputs: fields, page_size, page_start, campaign_id, +4 more.
list_ad_accountsC
List LinkedIn ad accounts accessible by the token
Inputs: test, fields, search, page_size, +2 more.
list_campaign_groupsC
List campaign groups for an ad account
Inputs: test, fields, search, page_size, +3 more.
list_campaignsC
List campaigns for an ad account
Inputs: test, fields, search, page_size, +3 more.
list_creativesC
List creatives for an ad account. Optional fields imageUrl and metadata use one extra GET per creative on API 202610+. Image URLs are external and may expire; restricted dashboards need approved embedded/local assets.
Inputs: fields, page_size, page_token, sort_order, +3 more.
search_ad_libraryA
Search public LinkedIn ads, including other advertisers, by keyword, advertiser, payer, country, dates, targeting categories and impression range. No ad account required. Requires the LinkedIn Ad Library product on the token's app, with no extra OAuth scope. Returns preview URLs and available transparency details; no ad copy/media download, clicks or spend. Targeting/impression details depend on availability (particularly EU ads). Without dates LinkedIn searches only today-2 to today-1. date_to is exclusive. Multiple keywords use AND.
Inputs: date_to, keyword, countries, date_from, +9 more.
search_brand_partnershipsA
Search organic LinkedIn posts declared by creators as brand partnerships. Returns post URLs. Requires the LinkedIn Ad Library product, no extra OAuth scope or ad account. Multiple keywords use AND. Without date_range searches available posts up to one year old.
Inputs: keyword (required), page_size, date_range, page_start.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Most tools map to clearly distinct resources and actions, and the descriptions explicitly separate similar areas such as login status vs. connection status and creative metadata vs. creative media. Minor overlap between connection_status/linkedin_login_status and get_creative/get_creative_media/get_share_content keeps it from being fully unambiguous.
The core tool set consistently uses snake_case verb_noun patterns such as list_campaigns, get_ad_account, and search_ad_library. The main deviations are the auth/status tools (connection_status, linkedin_login, linkedin_login_status), which are readable but do not follow the same verb-first convention.
Seventeen tools is slightly above the ideal band but reasonable for a LinkedIn Ads surface spanning auth, accounts, campaigns, creatives, insights, and ad-library searches. Each tool appears to serve a distinct function rather than duplicating another.
The server covers read/analytics/media/ad-library workflows broadly, including authentication and live status checks. However, it lacks create, update, delete, pause/resume, and budget-management operations for campaigns, creatives, and accounts, leaving the ads lifecycle notably incomplete.
Maintenance
Related MCP Connectors
LinkedIn Ads MCP server: run LinkedIn campaigns, ad groups, ads and reports from AI.
MCP server for querying and analyzing data from ad platforms, analytics tools, and spreadsheets
Managed LinkedIn MCP server for AI agents: search, connect, message and enrich on accounts you own.
A hosted LinkedIn MCP server for your own account. Paste one address into Claude, ChatGPT, Cursor or n8n to read your inbox, send messages and invitations, and search people. Free to start. Not made by LinkedIn.
Related MCP Servers
- FlicenseBqualityDmaintenanceAn MCP server that connects Claude to the LinkedIn Ads API for natural-language control over campaign management, audience targeting, creative uploads, analytics, and account auditing.37-
- AlicenseAqualityBmaintenanceMCP server for the LinkedIn Marketing API — query campaigns, performance, and Lead Gen Forms from Claude in plain English. 19 read-only tools covering ad accounts, campaigns, creatives, performance analytics, demographics, video analytics, budget pacing, period comparisons, conversions, Lead Gen Forms, audiences, and targeting facets. Built for B2B paid social teams.194-
- AlicenseAqualityFmaintenanceA read-write MCP server for managing Google Ads campaigns, ad groups, keywords, and ads via natural language.122-
- AlicenseBqualityDmaintenanceRead-only MCP server for Google Ads API, enabling natural language queries about campaigns, metrics, search terms, and change history without write access.6MIT