mcp-linkedin-ads
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., "@mcp-linkedin-ads show me campaign performance for last quarter"
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.
LinkedIn Ads MCP Server
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-adsAn 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-adsConfiguration
Security: Never share your .mcp.json file or commit it to git -- it may contain API credentials. Add .mcp.json to your .gitignore.
Get OAuth credentials:
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
Create
config.json:cp config.example.json config.jsonFill 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" } } }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 |
| yes | -- | OAuth client ID |
| yes | -- | OAuth client secret |
| yes | -- | OAuth access token |
| optional | -- | OAuth refresh token (rotated automatically when set) |
| optional |
| Set to |
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 |
| read — every predictive audience in an account, with locations, seeds, size, build status |
| read — one audience by parent DMP segment id |
| write — parent DMP segment + audience, then read-back; |
| write — partial update of name, locations, seeds, desired size; |
Requirements and behaviour (verified live 2026-11-05):
The token needs the
rw_dmp_segmentsscope (included inconfig.example.json). LinkedIn grants DMP write access per developer app.These calls use
LinkedIn-Version: 202607regardless ofapi.version; the audience endpoints 404 at 202604.desired_audience_countand at least oneurn: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_idinstead 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), NOTclicks(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 activeACTIVE— Actively servingPAUSED— Paused manuallyARCHIVED— Historical record
Audience Targeting
Flexible targeting:
flexible_specarray (OR logic between items)Exclude targeting:
exclude_specarrayJob 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 testsArchitecture
Files:
src/index.ts— MCP server, OAuth flow, tool handlerssrc/tools.ts— Tool schema definitionssrc/errors.ts— Error handling & classificationconfig.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
Define schema in
src/tools.tsAdd handler in
src/index.tstool dispatchTest with contract test in
.contract.test.tsDocument in here
Testing
npm test -- --run # Single run
npm test -- --watch # Watch modeTroubleshooting
Config file not found
cp config.example.json config.json
# Fill in your OAuth credentials and account IDsMissing required credentials
Check that:
LINKEDIN_ADS_CLIENT_IDandLINKEDIN_ADS_CLIENT_SECRETare set (or in config.json)config.jsonexists and contains at least one client withaccount_idOAuth 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:
Add tests for new tools
Update README with new features
Follow existing code style
Tag release with version
Support
Issues: GitHub issues for bugs/feature requests
Docs: See
docs/folder for detailed API referenceCommunity: 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 toolslinkedin_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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Meta, TikTok, LinkedIn, Snapchat and Reddit ads in Claude. Connect an ad account first.
Run Google Ads, Meta Ads, LinkedIn Ads and ChatGPT Ads from Claude or ChatGPT. You approve every change.
Manage Google, Meta, TikTok, Snapchat and LinkedIn ads, plus GA4, Tag Manager and Search Console, by chat from Claude or ChatGPT. Spend increases need your confirmation first.
Ask Claude about your ads: Meta, Google, TikTok, LinkedIn, GA4 & Shopify. No AI credits.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables Claude Desktop to manage your LinkedIn profile and company pages, including posting, reading posts, and fetching profile information.74MIT
- AlicenseAqualityDmaintenanceEnables posting content, sharing articles, and managing your LinkedIn profile through Claude using the official LinkedIn API with OAuth 2.0.6MIT
- AlicenseNot gradedqualityCmaintenanceEnables management and analysis of LinkedIn ad campaigns, including listing accounts, campaigns, creatives, and retrieving analytics, through natural language queries.82 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables 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.42MIT