io.github.mharnett/linkedin-ads
MCP server for LinkedIn Campaign Manager β campaigns, creatives, and analytics
Ask AI about io.github.mharnett/linkedin-ads
Powered by Claude Β· Grounded in docs
I know everything about io.github.mharnett/linkedin-ads. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
LinkedIn Ads MCP Server
Production-grade MCP server for LinkedIn Campaign Manager API. Enables Claude to manage LinkedIn ad accounts, campaigns, ad sets, and creatives with full read/write support.
Features:
- 7 tools -- 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: Flowspace, Forcepoint, Neon One
- π CTR accuracy: Uses
landingPageClicks(not total clicks with engagement) - β Full test coverage: 40+ contract tests
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.
-
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
-
Create
config.json:cp config.example.json config.json -
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" } } } -
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
The LinkedIn Ads MCP currently ships with read-only tools only. The write-mode
gate is already in place so that any future create/update/pause/enable/remove
tool is 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 and matches the pattern being rolled out to
Bing / Reddit / Meta. Motivation: prevent a casual LLM request from mutating
production ad accounts without the operator explicitly opting in.
Usage
Start the server
npm start
Use with Claude Code
Add to ~/.claude.json:
{
"mcpServers": {
"linkedin-ads": {
"type": "http",
"url": "http://localhost:3001"
}
}
}
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_specarray - 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 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.ts - Add handler in
src/index.tstool dispatch - Test with contract test in
.contract.test.ts - 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_IDandLINKEDIN_ADS_CLIENT_SECRETare set (or in config.json)config.jsonexists and contains at least one client withaccount_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:
- 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 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 10 tools.
Last Updated: 2026-03-13
