Skip to main content
Glama
flin-linkedin-ads-mcp

flin-linkedin-ads-mcp

by flin-agency

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)

  1. Desktop-Paket herunterladen und mit Claude Desktop öffnen. Alternativ: Einstellungen → Desktop-App → Erweiterungen verwalten → Erweiterte Einstellungen → Erweiterung installieren.

  2. 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.

  3. Persönlich anmelden: „Verbinde mich mit LinkedIn Ads“ schreiben und den Link von linkedin_login auf demselben Mac öffnen. Mit dem eigenen LinkedIn-Konto anmelden; dieses braucht Zugriff auf die Werbekonten. Die App benötigt r_ads und r_ads_reporting sowie die registrierte Rückleitungsadresse http://localhost:9876/callback.

  4. Verbindung prüfen: connection_status zeigt 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_login

  • Automatische 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 202610 als 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:

  1. Settings öffnen

  2. Developer öffnen

  3. MCP Config bearbeiten

  4. 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:

  1. linkedin_login und den zurückgegebenen Link öffnen

  2. linkedin_login_status (nach erfolgreichem Login: token_available)

  3. list_ad_accounts

  4. list_campaigns

  5. get_insights mit pivot=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 analytics Finder mit Single-Pivot.

  • Implementierung ist auf die Dokumentation view=li-lms-2026-03 ausgerichtet.

  • date_from ist Pflicht (LinkedIn adAnalytics erwartet dateRange).

  • Unterstützte fields folgen der Metrics-Tabelle aus der offiziellen Reporting-Schema-Doku (max. 20 Felder pro Request).

  • Der Server nutzt intern pivot.value / timeGranularity.value und 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_from und date_to: gemeinsam im Format YYYY-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_from und impressions_to: gemeinsam als Impression-Bereich; 1000000 bis 0 steht für die offene oberste Klasse ab einer Million.

  • sort_order: ASCENDING oder DESCENDING, sortiert nach Erstellungszeit der Anzeige.

  • page_start: Offset ab 0; page_size: 1 bis 25, Standard 25.

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: optional PAST_24H, PAST_WEEK oder PAST_MONTH; ohne Filter sind verfügbare Beiträge bis maximal ein Jahr nach Veröffentlichung durchsuchbar.

  • page_start und page_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, conversion

  • time_granularity: DAILY, MONTHLY, ALL, YEARLY

  • fields: Liste aus der offiziellen Metrics-Tabelle, maximal 20 Einträge, case-sensitive

    • Kompatibilitätsfelder: pivotValue → pivotValues, clickThroughRate (berechnet als clicks / impressions), costPerClick (berechnet als costInLocalCurrency / clicks)

  • date_from: YYYY-MM-DD (Pflicht)

  • date_to: optional, YYYY-MM-DD

Facets/Filter:

  • ad_account_id (ein Konto) oder account_ids (mehrere Konten)

  • optional zusätzlich: campaign_ids, campaign_group_ids, creative_ids, share_ids, company_ids

  • optional: campaign_type, objective_type

  • optional Sortierung: sort_by_field + sort_order (müssen zusammen angegeben werden)

Kompatibilität:

  • entity_ids bleibt für Backward-Kompatibilität erhalten (z. B. bei pivot=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 202610 wird imageUrl bevorzugt aus metadata.assetURL der einzelnen Creative-Abfrage gelesen. Dafür ist kein Zugriff auf die Posts-API nötig.

  • get_creative fordert das Metadatum im selben Aufruf an; list_creatives macht nur bei angefordertem imageUrl oder metadata eine zusätzliche Abfrage je Creative (doppelte IDs werden pro Seite zwischengespeichert). Ohne diese Felder bleibt es bei einer Listenabfrage.

  • metadata kann zusätzlich in fields angefordert werden und enthält je nach Format u. a. adHeadline, adIntroductionText, adFormat, assetURL und landingPage. Auf älteren API-Versionen wird eine ausdrückliche Anfrage nach metadata mit einem Konfigurationshinweis abgelehnt.

  • Fehlt eine Bildadresse in den Metadaten, wird der Creative-content geprüft.

  • Falls dort keine Bild-URL enthalten ist und eine content.reference auf urn:li:adDirectSponsoredContent:* zeigt, versucht der MCP zusätzlich eine Auflösung über adDirectSponsoredContents/{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 standardUpdateAd und videoAd werden erkannt.

  • Wenn keine Bild-URL auflösbar ist, ist imageUrl null.

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_DAYS

  • optional: ad_segment_ids, campaign_id

  • optional: skip_company_decoration

  • optional: page_start, page_size (max. 1000)

Wichtige Response-Felder:

  • companyName, engagementLevel

  • paidImpressions, paidClicks, paidEngagements, paidLeads

  • paidQualifiedLeads, conversions (ab API-Version 202603)

  • 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, Format urn:li:share:<id> oder urn:li:ugcPost:<id>)

  • include_raw (optional, true gibt zusätzlich das rohe API-Payload zurück)

Response enthält u. a.:

  • share_urn, source_endpoint (posts)

  • post_url (LinkedIn Feed URL)

  • text

  • image_url (erstes gefundenes Bild oder null)

  • 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, video für die vollständige MP4.

  • output: inline für ein MCP-Bild ohne lokale Datei, file für eine lokale Datei, both (Standard) für beides. Videos unterstützen file und both; beide liefern eine Datei und einen Dateiverweis, keinen nativen Video-Block.

  • Die Textantwort enthält mime_type, size_bytes, sha256 und bei Dateiausgabe local_path / file_uri. Bilddaten werden separat als MCP ImageContent ausgegeben, nicht als Base64 im Antworttext.

  • Speicherort: ~/.cache/flin-linkedin-ads-mcp/media, konfigurierbar mit LINKEDIN_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 403 nennt kind: "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:

  1. Feldnamen sind exakt korrekt (clicks statt click, impressions statt impression).

  2. Maximal 20 fields.

  3. Mindestens ein gültiger Facet-Filter (ad_account_id/account_ids oder andere Facets).

  4. IDs im korrekten Format (Account/Campaign/Campaign Group/Creative numerisch oder URN; share_ids und company_ids als URN).

  5. Datum im Format YYYY-MM-DD.

  6. date_from ist gesetzt (ohne dateRange antwortet LinkedIn oft mit ILLEGAL_ARGUMENT).

  7. pivot ist 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:

  1. In der LinkedIn Developer App den Marketing-/Advertising-Zugang mit r_ads und r_ads_reporting freischalten. Der anmeldende Benutzer braucht Zugriff auf das Werbekonto.

  2. Unter Auth die Redirect URL http://localhost:9876/callback registrieren.

  3. LINKEDIN_CLIENT_ID und LINKEDIN_CLIENT_SECRET in der MCP-Konfiguration hinterlegen (siehe Beispiel oben). Secrets gehören nicht in den Chat.

  4. 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_login liefert authorization_url. Den Link im lokalen Browser öffnen.

  • Der Server nimmt die Rückleitung automatisch entgegen und speichert den Token.

  • linkedin_login_status zeigt den lokalen Status; token_available bestätigt noch keine Kontoberechtigungen. Mit list_ad_accounts den echten API-Zugriff prüfen.

  • Anschliessend den ursprünglichen Call wiederholen, zum Beispiel get_ad_account mit {"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_login aufrufen 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_ID und LINKEDIN_CLIENT_SECRET (immer zusammen setzen)

  • LINKEDIN_REDIRECT_URI (Default: http://localhost:9876/callback; HTTP, localhost oder 127.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 src

Sicherheit (wichtig)

  • Niemals LINKEDIN_ACCESS_TOKEN oder OAuth Secrets ins Repo committen

  • .env ist bereits in .gitignore

  • App-Zugangsdaten nur über MCP env oder lokale Shell-Umgebung setzen; OAuth-Tokens werden lokal gespeichert

  • Vor jedem Push prüfen:

git status
git diff -- .env

Wenn 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.yml

  • Release Workflow: .github/workflows/release.yml

Der Release-Workflow macht bei v* Tags:

  1. Lint, Typecheck, Tests und Schwachstellenabgleich mit festgeschriebenen Abhängigkeiten

  2. Python- und MCPB-Build, twine check, Manifestprüfung und MCP-Starttest

  3. Trusted Publishing zu PyPI (Environment pypi) mit anschliessender Prüfung aller Datei-Hashes

  4. Erst 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: true in 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-mcp

  • Owner: flin-agency

  • Repository: flin-linkedin-ads-mcp

  • Workflow: release.yml

  • Environment: pypi

Release auslösen

git add -A
git commit -m "release: v0.1.0"
git tag v0.1.0
git push origin main --tags

Offizielle Referenzen

Available Tools

17 tools
connection_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.

get_share_contentA

Resolve LinkedIn share/ugcPost content via the Posts and Images APIs. Requires their additional permissions. For ad images prefer get_creative with imageUrl on API 202610+. External image URLs alone cannot bypass dashboard restrictions.

Inputs: share_urn (required), include_raw.

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

    B3.1/5.0

    Scored across 17 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP 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.
      19
      4
      -
    • A
      license
      A
      quality
      F
      maintenance
      A read-write MCP server for managing Google Ads campaigns, ad groups, keywords, and ads via natural language.
      12
      2
      -
    • A
      license
      B
      quality
      D
      maintenance
      Read-only MCP server for Google Ads API, enabling natural language queries about campaigns, metrics, search terms, and change history without write access.
      6
      MIT