LinkedIn Ads MCP Server
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., "@LinkedIn Ads MCP Server Show me last month's LinkedIn ad campaign performance"
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
An MCP (Model Context Protocol) server that enables Claude AI to access and analyze your LinkedIn Ads data. Built for marketers, founders, and growth teams who want to leverage AI for campaign optimization, performance reporting, and data-driven advertising decisions.
Quick Install (No Coding Required!)
Don't want to deal with technical stuff? Just copy one of the prompts below and paste it into Claude. The AI will do everything for you!
Option 1: Install with Claude Code (Recommended)
If you have Claude Code installed, just copy and paste this entire prompt:
I want you to install the LinkedIn Ads MCP server so I can analyze my LinkedIn advertising data. Please do the following:
1. FIRST, check if Node.js is installed by running `node --version`. If not installed, tell me to install it from https://nodejs.org first.
2. Clone the repository to my home directory:
- cd ~
- git clone https://github.com/danielpopamd/linkedin-ads-mcp.git
- cd linkedin-ads-mcp
3. Install dependencies and build:
- npm install
- npm run build
4. Create the .env file with placeholder values:
- cp .env.example .env
5. NOW IMPORTANT - Ask me for my LinkedIn API credentials:
- Ask: "Please provide your LinkedIn Client ID (from https://www.linkedin.com/developers/apps)"
- Ask: "Please provide your LinkedIn Client Secret"
6. Update the .env file with the credentials I provide.
7. Set up Claude Desktop configuration:
- Read the current Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%/Claude/claude_desktop_config.json
- Add the linkedin-ads MCP server to mcpServers (merge with existing config if any):
{
"mcpServers": {
"linkedin-ads": {
"command": "node",
"args": ["<FULL_PATH_TO>/linkedin-ads-mcp/dist/index.js"],
"env": {
"LINKEDIN_CLIENT_ID": "<MY_CLIENT_ID>",
"LINKEDIN_CLIENT_SECRET": "<MY_CLIENT_SECRET>"
}
}
}
}
- Replace <FULL_PATH_TO> with the actual path (e.g., /Users/username)
- Replace the env values with my actual credentials
8. Run the authentication flow:
- npm run auth
- This will open my browser - tell me to authorize the app with LinkedIn
9. Tell me to restart Claude Desktop to activate the MCP server.
10. After restart, confirm setup by telling me to ask Claude: "List my LinkedIn ad accounts"
If you don't have my LinkedIn API credentials yet, first explain how to get them:
- Go to https://www.linkedin.com/developers/apps
- Create a new app (need a LinkedIn Company Page)
- Go to Products tab and request "Advertising API" access
- Go to Auth tab and add redirect URL: http://localhost:3000/callback
- Copy the Client ID and Client Secret
Start now!Related MCP server: linkedin-campaign-manager-mcp
Option 2: Install with Claude Desktop (Chat-Based)
If you're using Claude Desktop directly (without Claude Code), copy this prompt to start a guided setup:
I want to install the LinkedIn Ads MCP server to analyze my LinkedIn advertising data with Claude. I'm not technical, so please guide me step by step with simple instructions.
Please walk me through:
1. **Check Prerequisites**
- Do I have Node.js installed? (Tell me how to check and where to download if needed)
- Do I have a LinkedIn Developer App? (If not, guide me through creating one at https://www.linkedin.com/developers/apps)
2. **Get LinkedIn API Access**
Walk me through:
- Creating a LinkedIn Developer App
- Requesting Advertising API access (Products tab)
- Adding the redirect URL: http://localhost:3000/callback (Auth tab)
- Finding my Client ID and Client Secret
3. **Download and Install**
Give me the exact commands to run in my terminal (one at a time):
- How to open Terminal (Mac) or Command Prompt (Windows)
- Clone the repository
- Install dependencies
- Build the project
4. **Configure Claude Desktop**
- Tell me exactly where the config file is located
- Give me the exact JSON to add (with placeholders for my credentials)
- Show me how to edit the file
5. **Authenticate with LinkedIn**
- What command to run
- What to do when the browser opens
6. **Test the Setup**
- Tell me to restart Claude Desktop
- Give me a test question to ask
Please start with step 1 and wait for my response before moving to the next step. Use simple language and assume I've never used a terminal before.What You'll Need Before Installing
Before using either installation method, you'll need:
Node.js (version 18 or higher) - Download here
A LinkedIn Company Page - Required to create a developer app
LinkedIn Developer App with Advertising API access - Create one here
Getting LinkedIn API Credentials (5-10 minutes)
Click "Create App"
Fill in:
App name: "My LinkedIn Ads Analytics" (or anything you want)
LinkedIn Page: Select your company page
App logo: Upload any square image
After creating, go to "Products" tab → Request "Advertising API" (approval takes 1-5 days)
Go to "Auth" tab → Add redirect URL:
http://localhost:3000/callbackCopy your Client ID and Client Secret - you'll need these!
Created By
Daniel Popa - Performance Marketing Consultant & AI Automation Specialist
I help ambitious startups scale profitably through paid ads, conversion rate optimization, and data-driven growth strategies. With 10+ years in performance marketing and $100M+ in managed ad budgets, I now focus on implementing AI workflows and automation to improve marketing efficiency and performance.
This tool was built to bridge the gap between LinkedIn's advertising data and AI-powered analysis, making it easier for marketers to get actionable insights through natural language conversations with Claude.
Website: danielpopa.me
Focus: Performance Marketing, AI Automation, Growth Strategy
Manual Installation (For Developers)
If you prefer to install manually or want more control, follow the instructions below.
What This Does
This MCP server connects Claude Desktop (or any MCP-compatible client) to the LinkedIn Marketing API, allowing you to:
Query campaign performance using natural language
Analyze audience demographics to understand who's engaging with your ads
Track conversions and leads across your LinkedIn campaigns
Compare performance between time periods, campaigns, or campaign groups
Get AI-powered insights on your advertising data
Example Conversations with Claude
"Show me campaign performance for the last 30 days"
"Which job functions are responding best to my ads?"
"Compare this week's performance vs last week"
"What's my cost per lead for the lead gen campaigns?"
"Which creatives have the best CTR?"
"Show me the daily trend for conversions"Features
25 Specialized Tools - Covering accounts, campaigns, creatives, audiences, conversions, analytics, and full campaign management (create, update, delete)
Comprehensive Metrics - Every report includes: Spend, Impressions, Clicks, CTR, Reach, Frequency, Engagements, Engagement Rate, CPM, CPC, Conversions, Conversion Rate, Cost per Conversion, Audience Penetration, and Average Dwell Time
Single OAuth Authentication - Authenticate once and access all your LinkedIn ad accounts
Automatic Token Refresh - Tokens refresh automatically before expiration
Rate Limit Handling - Built-in exponential backoff for API rate limits
Human-Readable Names - Demographic data shows actual names (not IDs) for seniorities, job functions, industries, and more
Prerequisites
1. LinkedIn Developer App
Before using this MCP server, you need to set up a LinkedIn Developer application:
Click "Create App"
Fill in your app details:
App name: e.g., "My LinkedIn Ads Analytics"
LinkedIn Page: Select your company page
App logo: Upload a logo (required)
Note your Client ID and Client Secret
2. Request Advertising API Access
In your app, go to the "Products" tab
Select "Advertising API"
Submit the request form with your business justification
Wait for approval (typically 1-5 business days)
3. Configure OAuth
Go to the "Auth" tab in your app
Add this redirect URL:
http://localhost:3000/callbackVerify these OAuth 2.0 scopes are available:
r_ads- Read ad accountsr_ads_reporting- Read reporting datarw_ads- Create and manage campaigns, creatives, and adsr_organization_social- Read organization posts (for creative content)
Installation
# Clone the repository
git clone https://github.com/danielpopamd/linkedin-ads-mcp.git
cd linkedin-ads-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Create your environment file
cp .env.example .envEdit .env with your LinkedIn credentials:
LINKEDIN_CLIENT_ID=your_client_id
LINKEDIN_CLIENT_SECRET=your_client_secretAuthentication
Run the authentication flow to get your access tokens:
npm run authThis will:
Open your browser to LinkedIn's OAuth page
Ask you to authorize the application
Store your tokens locally in
~/.linkedin-ads-mcp/tokens.jsonTokens are valid for 60 days and auto-refresh
Claude Desktop Setup
Add this to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"linkedin-ads": {
"command": "node",
"args": ["/full/path/to/linkedin-ads-mcp/dist/index.js"],
"env": {
"LINKEDIN_CLIENT_ID": "your_client_id",
"LINKEDIN_CLIENT_SECRET": "your_client_secret"
}
}
}
}Important: Replace /full/path/to/linkedin-ads-mcp with the actual path where you cloned this repository.
After updating the config, restart Claude Desktop for the changes to take effect.
Available Tools
Account Management
Tool | Description |
| List all accessible LinkedIn ad accounts |
| Get detailed account configuration and settings |
Campaign & Creative Performance
Tool | Description |
| Campaign metrics with all standard KPIs including audience penetration and average dwell time |
| Ad-level metrics with engagement, video stats, and average dwell time |
| List campaign groups with aggregated performance |
| List all campaigns including drafts and paused with zero impressions |
Audience & Demographics
Tool | Description |
| Performance by job function, industry, seniority, company size, country, region |
| Unique member reach, frequency, and native audience penetration metrics |
| View matched and lookalike audiences |
Conversions & Lead Generation
Tool | Description |
| Conversion metrics by conversion action |
| View conversion tracking rules and configuration |
| Lead form submissions and cost per lead |
| View lead gen form configurations |
Advanced Analytics
Tool | Description |
| Compare metrics between time periods or entities |
| Daily time-series data for trend analysis |
Campaign Management (Write Operations)
Tool | Description |
| Create a new campaign group for organizing campaigns |
| Update campaign group status, budget, name, or end date |
| Delete a campaign group |
| Create a new campaign with targeting, budget, and objective |
| Update campaign status, budget, targeting, or bid amount |
| Delete a campaign |
| Create a creative from an existing post/share |
| Create an ad with inline content (text, image, CTA) in one call |
| Activate, pause, or archive a creative |
| Upload an image for use in ads (PNG, JPG, GIF) |
Standard Metrics
Every performance report includes these metrics:
Metric | Description |
Spend | Total cost in USD |
Impressions | Number of times ads were shown |
Clicks | Total clicks on ads |
CTR | Click-through rate (%) |
Reach | Approximate unique members reached |
Frequency | Average impressions per unique member |
Engagements | Total engagements (likes, comments, shares, etc.) |
Engagement Rate | Engagements / Impressions (%) |
CPM | Cost per 1,000 impressions |
CPC | Cost per click |
Conversions | Total conversion events |
Conversion Rate | Conversions / Clicks (%) |
Cost per Conversion | Spend / Conversions |
Audience Penetration | Native LinkedIn metric: unique members reached / total target audience size (%). Uses API-native value when available (≤92 day range), with client-side fallback |
Average Dwell Time | Average seconds users spent with >50% of ad pixels visible in viewport |
API Limits & Best Practices
LinkedIn API Limits
Rate Limit: 45 million metric values per 5-minute window
Response Limit: Max 15,000 elements per response
Metrics per Request: Max 20 metrics
Demographic Data Delay: 12-24 hours
Reach Data: Max 92-day date range
Best Practices
Start with account listing - Always list accounts first to get valid account IDs
Use reasonable date ranges - Shorter ranges return faster; use 30 days for regular reporting
Be specific with campaigns - Filter by campaign IDs when you know which campaigns to analyze
Leverage comparisons - Use the compare tool to quickly identify performance changes
Project Structure
linkedin-ads-mcp/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── auth-cli.ts # OAuth CLI tool
│ ├── auth/
│ │ ├── oauth.ts # OAuth 2.0 flow
│ │ └── token-store.ts # Secure token storage
│ ├── lib/
│ │ ├── linkedin-api.ts # LinkedIn Marketing API client
│ │ └── types.ts # TypeScript type definitions
│ └── tools/
│ ├── accounts.ts # Account management tools
│ ├── performance.ts # Campaign & creative performance
│ ├── demographics.ts # Audience demographics tools
│ ├── conversions.ts # Conversion & lead gen tools
│ ├── analytics.ts # Advanced analytics tools
│ └── campaign-management.ts # Campaign CRUD & image upload tools
├── dist/ # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── .env.exampleDevelopment
# Build the project
npm run build
# Run the server (for testing)
npm run dev
# Run authentication flow
npm run authTroubleshooting
"Not authenticated" error
Run npm run auth to authenticate with LinkedIn.
"Rate limited" responses
The server automatically handles rate limits with exponential backoff. If you're hitting limits frequently, reduce the frequency of your requests.
Token expired
Tokens auto-refresh. If you're still having issues, delete ~/.linkedin-ads-mcp/tokens.json and re-authenticate with npm run auth.
API access denied
Ensure your LinkedIn Developer app has:
The "Advertising API" product approved
The correct OAuth scopes enabled (
r_ads,r_ads_reporting)Your user account has access to the ad accounts you're trying to query
Campaign names showing as "Unknown"
This typically means the campaign ID from analytics doesn't match any campaign in your account. This can happen with archived campaigns or if there's a sync delay.
Tech Stack
Model Context Protocol (MCP) - The protocol that enables Claude to interact with external tools
LinkedIn Marketing API - Official API for LinkedIn advertising data
TypeScript - Type-safe development
Node.js - Runtime environment
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
MIT License - see LICENSE file for details.
Acknowledgments
Built with the Model Context Protocol SDK by Anthropic.
Made with AI-powered workflows by Daniel Popa
Available Tools
25 toolscompare_performanceA
Compares performance between two time periods, campaigns, or campaign groups. Calculates percentage changes and highlights significant differences. Essential for reporting on performance trends.
Inputs: periodA (required), periodB (required), accountId (required), comparisonType (required).
create_campaignB
Creates a new LinkedIn ad campaign within a campaign group. Requires targeting criteria, budget, and objective type.
Inputs: name (required), accountId (required), objectiveType (required), unitCostAmount (required), +18 more.
create_campaign_groupA
Creates a new LinkedIn campaign group for organizing campaigns. Campaign groups manage status, budget, and performance across multiple related campaigns.
Inputs: name (required), accountId (required), startDate (required), status, +6 more.
create_creativeB
Creates a new LinkedIn creative/ad under a campaign. Requires a content reference (post/share URN) or will be created as a reference to existing content.
Inputs: accountId (required), campaignId (required), contentReference (required), name, +3 more.
create_inline_adA
Creates a new LinkedIn ad with inline content directly (without needing a pre-existing post). This creates the ad content (text, image/video, landing page, CTA) and the creative in a single call. Use this to create sponsored content ads from scratch.
Inputs: accountId (required), campaignId (required), commentary (required), organizationId (required), +8 more.
delete_campaignA
Deletes a LinkedIn campaign. Draft campaigns are deleted immediately. Non-draft campaigns are set to PENDING_DELETION status.
Inputs: accountId (required), campaignId (required).
delete_campaign_groupA
Deletes a LinkedIn campaign group. Draft groups are deleted immediately. Non-draft groups are set to PENDING_DELETION status.
Inputs: accountId (required), campaignGroupId (required).
get_account_detailsA
Retrieves detailed information about a specific LinkedIn Ad Account including status, currency, notification settings, and linked organization.
Inputs: accountId (required).
get_audience_demographicsB
Retrieves demographic breakdown of who saw or interacted with your ads. Shows performance segmented by job function, seniority, industry, company size, or geographic location. Essential for understanding if you're reaching your target audience. Note: Demographic data has a 12-24 hour delay.
Inputs: accountId (required), startDate (required), demographicType (required), limit, +3 more.
get_audience_reachA
Shows unique member reach and native audience penetration for campaigns. Returns LinkedIn's native audiencePenetration metric (approximate unique members reached / total target audience size). Helps understand what percentage of your target audience you've reached. Note: Date range must be 92 days or less.
Inputs: accountId (required), startDate (required), endDate, campaignIds, +1 more.
get_campaign_groupsC
Lists all campaign groups for an account with their configuration and optionally aggregated performance. Campaign groups help organize campaigns and control budget at a higher level.
Inputs: accountId (required), status, endDate, startDate, +1 more.
get_campaign_performanceA
Retrieves performance metrics for campaigns within a specified date range. Returns key metrics like impressions, clicks, spend, CTR, conversions, audience penetration, and average dwell time. The primary tool for daily campaign monitoring and optimization decisions.
Inputs: accountId (required), startDate (required), endDate, campaignIds, +2 more.
get_conversion_performanceA
Retrieves conversion metrics broken down by conversion type/action. Shows which conversions are being driven by which campaigns, with cost per conversion and conversion value.
Inputs: accountId (required), startDate (required), endDate, campaignIds, +2 more.
get_creative_performanceA
Retrieves performance metrics for individual ad creatives. Shows which specific ads are performing best, including engagement metrics (likes, comments, shares), video metrics, and average dwell time. Essential for creative optimization.
Inputs: accountId (required), startDate (required), endDate, campaignIds, +3 more.
get_daily_trendsB
Retrieves daily performance trends over a specified period. Returns time-series data for visualizing performance patterns, identifying anomalies, and understanding day-of-week effects.
Inputs: accountId (required), startDate (required), endDate, metrics, +2 more.
get_lead_gen_performanceB
Retrieves lead generation form performance including form submissions, qualified leads, and cost per lead. Essential for B2B marketers running lead gen campaigns.
Inputs: accountId (required), startDate (required), endDate, campaignIds, +1 more.
list_ad_accountsA
Lists all LinkedIn Ad Accounts accessible to the authenticated user. Returns account names, IDs, status, currency, and serving statuses. Use this to get an overview of all accounts or find a specific account ID.
Inputs: type, status, includeTest.
list_campaignsA
Lists campaigns for a LinkedIn Ad Account. Unlike get_campaign_performance (which only returns campaigns with analytics data), this tool returns ALL campaigns including DRAFT and PAUSED campaigns with zero impressions. Supports filtering by campaign group and status.
Inputs: accountId (required), status, campaignGroupIds.
list_conversionsA
Lists all conversion tracking rules configured for an account. Shows conversion names, types, attribution windows, and enabled status.
Inputs: accountId (required), enabledOnly.
list_lead_formsA
Lists all lead generation forms configured for an account with their questions and settings. Helps understand what forms are available and their configuration.
Inputs: accountId (required), status, includeQuestions.
list_saved_audiencesA
Lists saved/matched audiences available in the account for targeting. Shows audience names, sizes, and statuses to help plan campaign targeting.
Inputs: accountId (required), status, audienceType.
update_campaignA
Updates an existing LinkedIn campaign. Can change status (ACTIVE/PAUSED/ARCHIVED), budget, name, targeting, bid amount, and other settings. Uses partial update - only specified fields are changed.
Inputs: accountId (required), campaignId (required), name, status, +11 more.
update_campaign_groupA
Updates an existing LinkedIn campaign group. Can change status (ACTIVE/PAUSED/ARCHIVED/DRAFT), budget, name, or end date.
Inputs: accountId (required), campaignGroupId (required), name, status, +3 more.
update_creative_statusB
Updates the intended status of a LinkedIn creative/ad. Can activate, pause, or archive creatives.
Inputs: accountId (required), creativeId (required), intendedStatus (required).
upload_imageA
Uploads an image file to LinkedIn for use in ads. Supports PNG, JPG, and GIF formats. Returns the image URN that can be used as the mediaId when creating inline ads. The image is uploaded in two steps: initialize upload (get URL + URN), then upload binary.
Inputs: filePath (required), organizationId (required), accountId, assetName.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools target clearly distinct resource+action pairs, and descriptions proactively distinguish ambiguous cases (e.g. list_campaigns vs get_campaign_performance). The main overlap is between create_creative and create_inline_ad, which both produce creatives, plus a cluster of many performance-oriented get_* tools that an agent must read carefully to choose correctly.
All 25 tools follow a strict snake_case verb_noun pattern (list_, get_, create_, update_, delete_, upload_) with predictable resource names. There are no naming style deviations or vague verbs.
At 25 tools this sits at the heavy edge of the rubric; each tool maps to a real LinkedIn Ads concept (campaigns, groups, creatives, audiences, conversions, lead forms, analytics) so none are obviously trivial. However, the large analytics surface (eight get_*/compare/daily_trends tools) makes the set bulky and pushes it toward the 'heavy' band.
Core lifecycle coverage is strong: full CRUD on campaigns and campaign groups, plus create/update for creatives and rich performance/analytics and conversion/lead-form reads. Minor gaps exist—no delete_creative, audiences and conversions are read-only (no create/update), and there is no account-level rollup performance—but agents can work around these.
Maintenance
Related MCP Connectors
LinkedIn Ads MCP server: run LinkedIn campaigns, ad groups, ads and reports from AI.
Meta, TikTok, LinkedIn, Snapchat and Reddit ads in Claude. Connect an ad account first.
Open-source ad agent for LinkedIn Ads and Google Ads. Drafts campaigns, audiences and reports.
LinkedIn ads, ABM and CRM data for AI agents: reports, audits, and campaign management.
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-
- AlicenseAqualityBmaintenanceEnables Claude to manage LinkedIn ad accounts, campaigns, ad sets, and creatives with read/write support, including performance analytics and accurate CTR calculation using landing page clicks.9331 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables management and analysis of LinkedIn ad campaigns, including listing accounts, campaigns, creatives, and retrieving analytics, through natural language queries.82 npmMIT