{
  "markdown": "# LinkedIn Ads MCP Server\r\n\r\n[![npm version](https://img.shields.io/npm/v/mcp-linkedin-ads)](https://www.npmjs.com/package/mcp-linkedin-ads)\r\n[![npm downloads](https://img.shields.io/npm/dm/mcp-linkedin-ads)](https://www.npmjs.com/package/mcp-linkedin-ads)\r\n[![GitHub stars](https://img.shields.io/github/stars/mharnett/mcp-linkedin-ads)](https://github.com/mharnett/mcp-linkedin-ads)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n\r\nProduction-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.\r\n\r\n**Features:**\r\n- **7 tools** -- production-tested\r\n- Multi-account management (multiple LinkedIn ad accounts)\r\n- Campaign and campaign group listing\r\n- Account and campaign performance analytics\r\n- Flexible pivot-based reporting (demographics, device, creative breakdowns)\r\n- Landing page click-based CTR (not total clicks)\r\n\r\n**Stats:**\r\n- ⭐ Production-proven: active campaigns under management\r\n- 📊 Multi-client: Flowspace, Forcepoint, Neon One\r\n- 🔄 CTR accuracy: Uses `landingPageClicks` (not total clicks with engagement)\r\n- ✅ Full test coverage: 40+ contract tests\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm install mcp-linkedin-ads\r\n```\r\n\r\n## Configuration\r\n\r\n**Security:** Never share your `.mcp.json` file or commit it to git -- it may contain API credentials. Add `.mcp.json` to your `.gitignore`.\r\n\r\n1. **Get OAuth credentials:**\r\n   - Go to [LinkedIn Developer Portal](https://www.linkedin.com/developers/apps)\r\n   - Create a new app with \"Sign In with LinkedIn\" + \"Marketing Developer Platform\"\r\n   - Scopes: `r_ads`, `rw_ads`, `w_member_social`, `r_organization_social`, `w_organization_social`\r\n\r\n2. **Create `config.json`:**\r\n   ```bash\r\n   cp config.example.json config.json\r\n   ```\r\n\r\n3. **Fill in your credentials:**\r\n   ```json\r\n   {\r\n     \"oauth\": {\r\n       \"client_id\": \"YOUR_CLIENT_ID\",\r\n       \"client_secret\": \"YOUR_CLIENT_SECRET\"\r\n     },\r\n     \"clients\": {\r\n       \"default\": {\r\n         \"account_id\": \"YOUR_AD_ACCOUNT_ID\",\r\n         \"name\": \"My Account\"\r\n       }\r\n     }\r\n   }\r\n   ```\r\n\r\n4. **Set environment variables (recommended for production):**\r\n   ```bash\r\n   export LINKEDIN_ADS_CLIENT_ID=\"your_client_id\"\r\n   export LINKEDIN_ADS_CLIENT_SECRET=\"your_client_secret\"\r\n   export LINKEDIN_ADS_ACCESS_TOKEN=\"your_access_token\"\r\n   ```\r\n\r\n### Environment variables\r\n\r\n| Variable | Required | Default | Purpose |\r\n|---|---|---|---|\r\n| `LINKEDIN_ADS_CLIENT_ID` | yes | -- | OAuth client ID |\r\n| `LINKEDIN_ADS_CLIENT_SECRET` | yes | -- | OAuth client secret |\r\n| `LINKEDIN_ADS_ACCESS_TOKEN` | yes | -- | OAuth access token |\r\n| `LINKEDIN_ADS_REFRESH_TOKEN` | optional | -- | OAuth refresh token (rotated automatically when set) |\r\n| `LINKEDIN_ADS_MCP_WRITE` | optional | `false` | Set to `true` to expose mutating tools. Read-only by default. |\r\n\r\n### Read-only by default\r\n\r\nThe LinkedIn Ads MCP currently ships with read-only tools only. The write-mode\r\ngate is already in place so that any future create/update/pause/enable/remove\r\ntool is hidden from `ListTools` and refused at call time unless\r\n`LINKEDIN_ADS_MCP_WRITE=true` is set in the MCP server environment. This\r\nmirrors the Google Ads MCP gate and matches the pattern being rolled out to\r\nBing / Reddit / Meta. Motivation: prevent a casual LLM request from mutating\r\nproduction ad accounts without the operator explicitly opting in.\r\n\r\n## Usage\r\n\r\n### Start the server\r\n```bash\r\nnpm start\r\n```\r\n\r\n### Use with Claude Code\r\nAdd to `~/.claude.json`:\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"linkedin-ads\": {\r\n      \"type\": \"http\",\r\n      \"url\": \"http://localhost:3001\"\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n**Claude Desktop:** Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows).\r\n\r\n### Example API Calls\r\n```typescript\r\n// Get client context\r\nlinkedin_ads_get_client_context({ working_directory: \"/path/to/project\" })\r\n\r\n// List campaigns\r\nlinkedin_ads_list_campaigns({ account_id: \"511664399\" })\r\n\r\n// Get campaign performance\r\nlinkedin_ads_campaign_performance({\r\n  start_date: \"2026-01-01\",\r\n  end_date: \"2026-03-31\",\r\n  time_granularity: \"MONTHLY\"\r\n})\r\n\r\n// Flexible analytics (e.g. by seniority)\r\nlinkedin_ads_analytics({\r\n  start_date: \"2026-03-01\",\r\n  end_date: \"2026-03-31\",\r\n  pivot: \"MEMBER_SENIORITY\"\r\n})\r\n```\r\n\r\n## Key Data Conventions\r\n\r\n### CTR Calculation\r\n- Always use `landingPageClicks` (LP clicks), NOT `clicks` (total clicks)\r\n- Total clicks include social engagement (likes, comments, shares) which inflates CTR\r\n- **This is critical for accurate campaign analysis**\r\n\r\n### Campaign Status\r\n- `DRAFT` — Not yet active\r\n- `ACTIVE` — Actively serving\r\n- `PAUSED` — Paused manually\r\n- `ARCHIVED` — Historical record\r\n\r\n### Audience Targeting\r\n- Flexible targeting: `flexible_spec` array (OR logic between items)\r\n- Exclude targeting: `exclude_spec` array\r\n- Job titles, seniority levels, functions, locations all supported\r\n\r\n## CLI Tools\r\n\r\n```bash\r\nnpm run dev                 # Run in dev mode (tsx)\r\nnpm run build             # Compile TypeScript\r\nnpm test                  # Run contract tests\r\n```\r\n\r\n## Architecture\r\n\r\n**Files:**\r\n- `src/index.ts` — MCP server, OAuth flow, tool handlers\r\n- `src/tools.ts` — Tool schema definitions\r\n- `src/errors.ts` — Error handling & classification\r\n- `config.json` — Credentials & client mapping\r\n\r\n**Error Handling:**\r\n- OAuth errors: Clear messages for token refresh needed\r\n- Rate limits: Automatic retry with backoff (recommended by LinkedIn)\r\n- Invalid campaigns: Validation before creation (save API quota)\r\n\r\n## Development\r\n\r\n### Adding a New Tool\r\n1. Define schema in `src/tools.ts`\r\n2. Add handler in `src/index.ts` tool dispatch\r\n3. Test with contract test in `.contract.test.ts`\r\n4. Document in here\r\n\r\n### Testing\r\n```bash\r\nnpm test -- --run        # Single run\r\nnpm test -- --watch      # Watch mode\r\n```\r\n\r\n## Troubleshooting\r\n\r\n### `Config file not found`\r\n```bash\r\ncp config.example.json config.json\r\n# Fill in your OAuth credentials and account IDs\r\n```\r\n\r\n### `Missing required credentials`\r\nCheck that:\r\n- `LINKEDIN_ADS_CLIENT_ID` and `LINKEDIN_ADS_CLIENT_SECRET` are set (or in config.json)\r\n- `config.json` exists and contains at least one client with `account_id`\r\n- OAuth tokens are valid (they expire)\r\n\r\n### `Rate limit exceeded`\r\nLinkedIn enforces strict rate limits. The server includes automatic retry with exponential backoff. If you hit limits:\r\n- Wait before retrying\r\n- Batch operations when possible\r\n- Reduce query frequency\r\n\r\n### `CTR seems too low`\r\nVerify you're using `landingPageClicks` (LP clicks), not `clicks` (all interactions). The latter includes social engagement and will inflate CTR incorrectly.\r\n\r\n## License\r\n\r\nMIT\r\n\r\n## Contributing\r\n\r\nContributions welcome! Please:\r\n1. Add tests for new tools\r\n2. Update README with new features\r\n3. Follow existing code style\r\n4. Tag release with version\r\n\r\n## Support\r\n\r\n- **Issues:** GitHub issues for bugs/feature requests\r\n- **Docs:** See `docs/` folder for detailed API reference\r\n- **Community:** Discussions in GitHub\r\n\r\n---\r\n\r\n## Built By\r\n\r\n**[Mark Harnett](https://www.linkedin.com/in/markharnett/)** — 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.\r\n\r\nBuilt 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.\r\n\r\n**Also by Mark:** [mcp-bing-ads](https://github.com/mharnett/mcp-bing-ads) -- Bing/Microsoft Ads MCP server with 10 tools.\r\n\r\n**Last Updated:** 2026-03-13\r\n",
  "bytes": 7943,
  "sha": "1fdb003b8f43a0393b5295f2878d90da69ef8973896312ea8016135f8f615ff0",
  "repo_slug": "mharnett/mcp-linkedin-ads",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mharnett_linkedin_ads_045f2353/readme"
}