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.

[!TIP] Want this without any setup? From the same author: AdPlug is the hosted LinkedIn Ads MCP. Sign in with OAuth (no LinkedIn developer app, no credentials to manage), connect Claude, ChatGPT, or Cursor in about two minutes, and get Google Ads and Microsoft Ads on the same connector. Read tools are free; every write is previewed before it runs. This open-source server stays free and self-hosted.

---

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:

---

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:

---

What You’ll Need Before Installing

Before using either installation method, you’ll need:

1. Node.js (version 18 or higher) - Download here
2. A LinkedIn Company Page - Required to create a developer app
3. LinkedIn Developer App with Advertising API access - Create one here

Getting LinkedIn API Credentials (5-10 minutes)

1. Go to LinkedIn Developer Portal
2. Click “Create App”
3. Fill in:
   • App name: “My LinkedIn Ads Analytics” (or anything you want)
   • LinkedIn Page: Select your company page
   • App logo: Upload any square image
4. After creating, go to “Products” tab → Request “Advertising API” (approval takes 1-5 days)
5. Go to “Auth” tab → Add redirect URL: http://localhost:3000/callback
6. Copy 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:

1. Go to LinkedIn Developer Portal
2. Click “Create App”
3. 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)
4. Note your Client ID and Client Secret

2. Request Advertising API Access

1. In your app, go to the “Products” tab
2. Select “Advertising API”
3. Submit the request form with your business justification
4. Wait for approval (typically 1-5 business days)

3. Configure OAuth

1. Go to the “Auth” tab in your app
2. Add this redirect URL: http://localhost:3000/callback
3. Verify these OAuth 2.0 scopes are available:
   • r_ads - Read ad accounts
   • r_ads_reporting - Read reporting data
   • rw_ads - Create and manage campaigns, creatives, and ads
   • r_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 .env

Edit .env with your LinkedIn credentials:

LINKEDIN_CLIENT_ID=your_client_id
LINKEDIN_CLIENT_SECRET=your_client_secret

---

Authentication

Run the authentication flow to get your access tokens:

npm run auth

This will:

1. Open your browser to LinkedIn’s OAuth page
2. Ask you to authorize the application
3. Store your tokens locally in ~/.linkedin-ads-mcp/tokens.json
4. Tokens 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

Campaign & Creative Performance

Audience & Demographics

Conversions & Lead Generation

Advanced Analytics

Campaign Management (Write Operations)

---

Standard Metrics

Every performance report includes these metrics:

---

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

1. Start with account listing - Always list accounts first to get valid account IDs
2. Use reasonable date ranges - Shorter ranges return faster; use 30 days for regular reporting
3. Be specific with campaigns - Filter by campaign IDs when you know which campaigns to analyze
4. 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.example

---

Development

# Build the project
npm run build

# Run the server (for testing)
npm run dev

# Run authentication flow
npm run auth

---

Troubleshooting

“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:

1. The “Advertising API” product approved
2. The correct OAuth scopes enabled (r_ads, r_ads_reporting)
3. 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