Skip to main content
Glama
mcp-linkedin-ads

mcp-linkedin-ads

by mharnett

LinkedIn Ads MCP Server

npm version npm downloads GitHub stars License: MIT

Production-grade MCP server for LinkedIn Campaign Manager API. Enables Claude to report on LinkedIn ad accounts, campaign groups and campaigns, and to manage predictive (lookalike) audiences. Reporting is read-only; the two audience write tools are off unless enabled.

Quick install

Claude Code, one line (replace the placeholder values with your own; see Configuration for how to get them):

claude mcp add --env LINKEDIN_ADS_ACCESS_TOKEN=YOUR_ACCESS_TOKEN_HERE --transport stdio mcp-linkedin-ads -- npx -y mcp-linkedin-ads

An access token alone is enough to start. Add --env LINKEDIN_ADS_ACCOUNT_ID=YOUR_ACCOUNT_ID to set a default ad account. To refresh tokens automatically, also set LINKEDIN_ADS_CLIENT_ID and LINKEDIN_ADS_CLIENT_SECRET. The server uses LinkedIn API version 202607 and starts read-only; set LINKEDIN_ADS_MCP_WRITE=true to expose the two predictive-audience write tools.

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), then fully quit and restart Claude Desktop:

{
  "mcpServers": {
    "mcp-linkedin-ads": {
      "command": "npx",
      "args": ["-y", "mcp-linkedin-ads"],
      "env": {
        "LINKEDIN_ADS_ACCESS_TOKEN": "YOUR_ACCESS_TOKEN_HERE"
      }
    }
  }
}

Add this to ~/.codex/config.toml:

[mcp_servers.mcp-linkedin-ads]
command = "npx"
args = ["-y", "mcp-linkedin-ads"]

[mcp_servers.mcp-linkedin-ads.env]
LINKEDIN_ADS_ACCESS_TOKEN = "YOUR_ACCESS_TOKEN_HERE"

Features:

  • 11 tools (9 read, 2 write) -- production-tested

  • Multi-account management (multiple LinkedIn ad accounts)

  • Campaign and campaign group listing

  • Account and campaign performance analytics

  • Flexible pivot-based reporting (demographics, device, creative breakdowns)

  • Landing page click-based CTR (not total clicks)

Stats:

  • ⭐ Production-proven: active campaigns under management

  • 📊 Multi-client: per-client config, no client data in repo

  • 🔄 CTR accuracy: Uses landingPageClicks (not total clicks with engagement)

  • ✅ Full test coverage: 40+ contract tests

Related MCP server: linkedin-mcp-server

Installation

npm install mcp-linkedin-ads

Configuration

Security: Never share your .mcp.json file or commit it to git -- it may contain API credentials. Add .mcp.json to your .gitignore.

  1. Get OAuth credentials:

    • Go to LinkedIn Developer Portal

    • Create a new app with "Sign In with LinkedIn" + "Marketing Developer Platform"

    • Scopes: r_ads, rw_ads, w_member_social, r_organization_social, w_organization_social

  2. Create config.json:

    cp config.example.json config.json
  3. Fill in your credentials:

    {
      "oauth": {
        "client_id": "YOUR_CLIENT_ID",
        "client_secret": "YOUR_CLIENT_SECRET"
      },
      "clients": {
        "default": {
          "account_id": "YOUR_AD_ACCOUNT_ID",
          "name": "My Account"
        }
      }
    }
  4. Set environment variables (recommended for production):

    export LINKEDIN_ADS_CLIENT_ID="your_client_id"
    export LINKEDIN_ADS_CLIENT_SECRET="your_client_secret"
    export LINKEDIN_ADS_ACCESS_TOKEN="your_access_token"

Environment variables

Variable

Required

Default

Purpose

LINKEDIN_ADS_CLIENT_ID

yes

--

OAuth client ID

LINKEDIN_ADS_CLIENT_SECRET

yes

--

OAuth client secret

LINKEDIN_ADS_ACCESS_TOKEN

yes

--

OAuth access token

LINKEDIN_ADS_REFRESH_TOKEN

optional

--

OAuth refresh token (rotated automatically when set)

LINKEDIN_ADS_MCP_WRITE

optional

false

Set to true to expose mutating tools. Read-only by default.

Read-only by default

Write tools (currently linkedin_ads_create_predictive_audience and linkedin_ads_update_predictive_audience) are hidden from ListTools and refused at call time unless LINKEDIN_ADS_MCP_WRITE=true is set in the MCP server environment. This mirrors the Google Ads MCP gate. Motivation: prevent a casual LLM request from mutating production ad accounts without the operator explicitly opting in.

Each write also requires account_id and confirm_account_id set to the same id. The account is never resolved from the working directory or a default, and an update refuses a segment owned by a different account. Every write reads the object back and returns any field that did not stick as mismatches.

Predictive audiences (lookalikes)

Tool

Kind

linkedin_ads_list_predictive_audiences

read — every predictive audience in an account, with locations, seeds, size, build status

linkedin_ads_get_predictive_audience

read — one audience by parent DMP segment id

linkedin_ads_create_predictive_audience

write — parent DMP segment + audience, then read-back; dry_run supported

linkedin_ads_update_predictive_audience

write — partial update of name, locations, seeds, desired size; dry_run supported

Requirements and behaviour (verified live 2026-11-05):

  • The token needs the rw_dmp_segments scope (included in config.example.json). LinkedIn grants DMP write access per developer app.

  • These calls use LinkedIn-Version: 202607 regardless of api.version; the audience endpoints 404 at 202604.

  • desired_audience_count and at least one urn:li:geo: location are required on create.

  • Freshly created audiences 404 their POST/PATCH for a few seconds, and reads lag writes; the tools retry 404s and re-read before reporting a mismatch.

  • If create fails after the parent segment exists, the error names it; retry with existing_dmp_segment_id instead of creating a second parent.

  • Segments created after early September 2026 cannot be attached to campaigns through the API in our testing; attach them in Campaign Manager.

Usage

Use with Claude Code

The server runs locally over stdio; your MCP client starts it. Add to ~/.claude.json (or a project .mcp.json):

{
  "mcpServers": {
    "linkedin-ads": {
      "command": "npx",
      "args": ["-y", "mcp-linkedin-ads"],
      "env": {
        "LINKEDIN_ADS_CLIENT_ID": "your_client_id",
        "LINKEDIN_ADS_CLIENT_SECRET": "your_client_secret",
        "LINKEDIN_ADS_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Example API Calls

// Get client context
linkedin_ads_get_client_context({ working_directory: "/path/to/project" })

// List campaigns
linkedin_ads_list_campaigns({ account_id: "511664399" })

// Get campaign performance
linkedin_ads_campaign_performance({
  start_date: "2026-01-01",
  end_date: "2026-03-31",
  time_granularity: "MONTHLY"
})

// Flexible analytics (e.g. by seniority)
linkedin_ads_analytics({
  start_date: "2026-03-01",
  end_date: "2026-03-31",
  pivot: "MEMBER_SENIORITY"
})

Key Data Conventions

CTR Calculation

  • Always use landingPageClicks (LP clicks), NOT clicks (total clicks)

  • Total clicks include social engagement (likes, comments, shares) which inflates CTR

  • This is critical for accurate campaign analysis

Campaign Status

  • DRAFT — Not yet active

  • ACTIVE — Actively serving

  • PAUSED — Paused manually

  • ARCHIVED — Historical record

Audience Targeting

  • Flexible targeting: flexible_spec array (OR logic between items)

  • Exclude targeting: exclude_spec array

  • Job titles, seniority levels, functions, locations all supported

CLI Tools

npm run dev                 # Run in dev mode (tsx)
npm run build             # Compile TypeScript
npm test                  # Run contract tests

Architecture

Files:

  • src/index.ts — MCP server, OAuth flow, tool handlers

  • src/tools.ts — Tool schema definitions

  • src/errors.ts — Error handling & classification

  • config.json — Credentials & client mapping

Error Handling:

  • OAuth errors: Clear messages for token refresh needed

  • Rate limits: Automatic retry with backoff (recommended by LinkedIn)

  • Invalid campaigns: Validation before creation (save API quota)

Development

Adding a New Tool

  1. Define schema in src/tools.ts

  2. Add handler in src/index.ts tool dispatch

  3. Test with contract test in .contract.test.ts

  4. Document in here

Testing

npm test -- --run        # Single run
npm test -- --watch      # Watch mode

Troubleshooting

Config file not found

cp config.example.json config.json
# Fill in your OAuth credentials and account IDs

Missing required credentials

Check that:

  • LINKEDIN_ADS_CLIENT_ID and LINKEDIN_ADS_CLIENT_SECRET are set (or in config.json)

  • config.json exists and contains at least one client with account_id

  • OAuth tokens are valid (they expire)

Rate limit exceeded

LinkedIn enforces strict rate limits. The server includes automatic retry with exponential backoff. If you hit limits:

  • Wait before retrying

  • Batch operations when possible

  • Reduce query frequency

CTR seems too low

Verify you're using landingPageClicks (LP clicks), not clicks (all interactions). The latter includes social engagement and will inflate CTR incorrectly.

License

MIT

Contributing

Contributions welcome! Please:

  1. Add tests for new tools

  2. Update README with new features

  3. Follow existing code style

  4. Tag release with version

Support

  • Issues: GitHub issues for bugs/feature requests

  • Docs: See docs/ folder for detailed API reference

  • Community: Discussions in GitHub


Built By

Mark Harnett — Demand generation leader and paid media practitioner building AI-powered ad management tools. This server was born from managing LinkedIn campaigns across multiple clients and wanting Claude to handle campaign ops, performance analysis, and bulk creative updates autonomously.

Built with production workloads in mind: resilient API calls (circuit breakers, retry with backoff, response truncation), accurate CTR calculation (landing page clicks, not total clicks), and multi-account support.

Also by Mark: mcp-bing-ads -- Bing/Microsoft Ads MCP server with 13 tools.

Last Updated: 2026-03-13

Available Tools

9 tools
linkedin_ads_account_performanceA

Get account-level aggregate performance metrics for a date range. Good for high-level summaries. Note: reach (approximateMemberReach) and the derived frequency field are not populated at pivot=ACCOUNT; query at CAMPAIGN/CAMPAIGN_GROUP via linkedin_ads_campaign_performance or linkedin_ads_analytics if you need reach.

Inputs: end_date (required), start_date (required), account_id, time_granularity.

linkedin_ads_analyticsB

Flexible analytics query with custom pivot, fields, and filters. Use for demographic breakdowns, device splits, creative performance, etc.

Inputs: pivot (required), end_date (required), start_date (required), fields, +4 more.

linkedin_ads_campaign_performanceA

Get campaign-level performance metrics (impressions, clicks, spend, conversions, leads, engagement, video views, reach, frequency) for a date range. Reach = approximateMemberReach (unique members exposed); frequency = impressions / reach (computed server-side). This is the main reporting tool for weekly slides.

Inputs: end_date (required), start_date (required), account_id, time_granularity.

linkedin_ads_get_client_contextA

Get the current client context and health status based on working directory. Call this first to confirm which LinkedIn Ads account you're working with.

Inputs: working_directory (required).

linkedin_ads_get_predictive_audienceA

Get one LinkedIn Predictive Audience by its parent DMP segment id: name, account, destinations (build status, size), targetingFilter (locations), seeds, desiredAudienceCount and versionTag.

Inputs: dmp_segment_id (required).

linkedin_ads_list_accountsB

List all active LinkedIn Ad Accounts the authenticated user has access to.

Inputs: no named parameters.

linkedin_ads_list_campaign_groupsC

List campaign groups for a LinkedIn Ad Account.

Inputs: account_id.

linkedin_ads_list_campaignsC

List campaigns for a LinkedIn Ad Account, with optional status and campaign group filters.

Inputs: status, account_id, campaign_group_id.

linkedin_ads_list_predictive_audiencesA

List LinkedIn Predictive Audiences (lookalikes) in an ad account: each parent DMP segment with its name, destinations/build status, location filter, seeds and desiredAudienceCount. account_id is required (never taken from the working directory).

Inputs: account_id (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools target clearly distinct resources (accounts, campaigns, campaign groups, predictive audiences) and the descriptions explicitly state when to prefer one over another. The trio of campaign_performance, account_performance, and analytics does overlap, but the descriptions differentiate them by pivot/granularity (account-level lacks reach, analytics is the flexible custom query), which mitigates most misselection risk.

    Naming Consistency4/5

    All names use a uniform linkedin_ads_ prefix with snake_case, and most follow a verb_noun pattern (list_campaigns, get_client_context, list_predictive_audiences). Minor deviation: campaign_performance and account_performance drop the verb and use noun_noun, and analytics is a bare noun, but the pattern remains readable and predictable.

    Tool Count5/5

    Nine tools is well within the ideal 3-15 range and each one covers a distinct slice of the reporting surface (context, accounts, campaigns, groups, two performance levels, flexible analytics, two audience lookups). No filler or redundant tools are apparent.

    Completeness3/5

    The surface is coherent for a read-only reporting server (accounts, campaigns, groups, performance, predictive audiences), but it is entirely read-only: there is no create/update campaign, no get_campaign or get_campaign_group detail tool, and no ad/creative listing beyond what analytics returns. An agent wanting to drill into a single campaign's settings or manage entities hits a dead end.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables Claude Desktop to manage your LinkedIn profile and company pages, including posting, reading posts, and fetching profile information.
      7
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables posting content, sharing articles, and managing your LinkedIn profile through Claude using the official LinkedIn API with OAuth 2.0.
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables management and analysis of LinkedIn ad campaigns, including listing accounts, campaigns, creatives, and retrieving analytics, through natural language queries.
      82 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to access, analyze, and manage LinkedIn advertising data, including campaigns, creatives, audiences, and conversions, with full create, update, and delete capabilities plus analytics via natural language.
      42
      MIT