linkedin-ads

LinkedIn Ads MCP 服务

适用于生产环境的 LinkedIn Campaign Manager API MCP 服务。支持 Claude 管理 LinkedIn 广告账户、广告系列、广告组和创意，并提供完整的读写支持。

功能：

• 7 个工具——经过生产环境测试
• 多账户管理（多个 LinkedIn 广告账户）
• 广告系列和广告系列组列表
• 账户和广告系列表现分析
• 灵活的基于透视维度的报告（人口统计、设备、创意细分）
• 基于落地页点击量的 CTR（而非总点击量）

统计：

• ⭐ 经生产环境验证：正在管理活跃广告系列
• 📊 多客户：Flowspace、Forcepoint、Neon One
• 🔄 CTR 准确性：使用 landingPageClicks（而非包含互动量的总点击量）
• ✅ 完整测试覆盖：40 多项契约测试

安装

npm install mcp-linkedin-ads

配置

**安全性：**切勿分享 .mcp.json 文件，也不要将其提交到 git——其中可能包含 API 凭据。请将 .mcp.json 添加到 .gitignore。

1. 获取 OAuth 凭据：

   • 前往 LinkedIn Developer Portal
   • 创建一个新应用，并选择 "Sign In with LinkedIn" + "Marketing Developer Platform"
   • 权限范围：r_ads、rw_ads、w_member_social、r_organization_social、w_organization_social

2. 创建 config.json：

   cp config.example.json config.json
   

3. 填写凭据：

   {
     "oauth": {
       "client_id": "YOUR_CLIENT_ID",
       "client_secret": "YOUR_CLIENT_SECRET"
     },
     "clients": {
       "default": {
         "account_id": "YOUR_AD_ACCOUNT_ID",
         "name": "My Account"
       }
     }
   }
   

4. 设置环境变量（推荐用于生产环境）：

   export LINKEDIN_ADS_CLIENT_ID="your_client_id"
   export LINKEDIN_ADS_CLIENT_SECRET="your_client_secret"
   export LINKEDIN_ADS_ACCESS_TOKEN="your_access_token"
   

环境变量

变量	必需	默认值	用途
LINKEDIN_ADS_CLIENT_ID	是	--	OAuth 客户端 ID
LINKEDIN_ADS_CLIENT_SECRET	是	--	OAuth 客户端密钥
LINKEDIN_ADS_ACCESS_TOKEN	是	--	OAuth 访问令牌
LINKEDIN_ADS_REFRESH_TOKEN	否	--	OAuth 刷新令牌（设置后会自动轮换）
LINKEDIN_ADS_MCP_WRITE	否	false	设置为 true 以开放可变更数据的工具。默认只读。

默认只读

目前，LinkedIn Ads MCP 仅提供只读工具。写入模式的 限制机制已就绪；除非在 MCP 服务环境中设置 LINKEDIN_ADS_MCP_WRITE=true，否则任何未来新增的创建、更新、暂停、启用或移除 工具都不会显示在 ListTools 中，并且在调用时会被拒绝。这一机制 与 Google Ads MCP 的限制机制一致，也符合正在推广到 Bing / Reddit / Meta 的模式。这样做是为了防止 LLM 随意执行请求， 在操作人员未明确选择启用的情况下更改生产环境中的广告账户。

使用方法

启动服务

npm start

在 Claude Code 中使用

添加到 ~/.claude.json：

{
  "mcpServers": {
    "linkedin-ads": {
      "type": "http",
      "url": "http://localhost:3001"
    }
  }
}

**Claude Desktop：**添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。

API 调用示例

// 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"
})

关键数据约定

CTR 计算

• 始终使用 landingPageClicks（落地页点击量），不要使用 clicks（总点击量）
• 总点击量包含社交互动（点赞、评论、分享），会导致 CTR 虚高
• 这对准确分析广告系列至关重要

广告系列状态

• DRAFT — 尚未启用
• ACTIVE — 正在投放
• PAUSED — 手动暂停
• ARCHIVED — 历史记录

受众定向

• 灵活定向：flexible_spec 数组（各项之间采用 OR 逻辑）
• 排除定向：exclude_spec 数组
• 支持职位、资历、职能和地点

CLI 工具

npm run dev                 # Run in dev mode (tsx)
npm run build             # Compile TypeScript
npm test                  # Run contract tests

架构

文件：

• src/index.ts — MCP 服务、OAuth 流程、工具处理程序
• src/tools.ts — 工具架构定义
• src/errors.ts — 错误处理与分类
• config.json — 凭据与客户端映射

错误处理：

• OAuth 错误：针对需要刷新令牌的情况提供清晰的提示
• 速率限制：自动重试并采用退避策略（LinkedIn 推荐）
• 无效广告系列：创建前进行验证（节省 API 配额）

开发

添加新工具

1. 在 src/tools.ts 中定义架构
2. 在 src/index.ts 的工具分发逻辑中添加处理程序
3. 使用 .contract.test.ts 中的契约测试进行测试
4. 在此处编写文档

测试

npm test -- --run        # Single run
npm test -- --watch      # Watch mode

故障排查

Config file not found

cp config.example.json config.json
# Fill in your OAuth credentials and account IDs

Missing required credentials

请检查：

• 已设置 LINKEDIN_ADS_CLIENT_ID 和 LINKEDIN_ADS_CLIENT_SECRET（或将其配置在 config.json 中）
• config.json 存在，且至少包含一个带有 account_id 的客户端
• OAuth 令牌有效（令牌会过期）

Rate limit exceeded

LinkedIn 实施了严格的速率限制。该服务包含自动重试和指数退避机制。如果触及限制：

• 等待一段时间后再重试
• 尽可能批量处理操作
• 降低查询频率

CTR seems too low

请确认使用的是 landingPageClicks（落地页点击），而不是 clicks（所有互动）。后者包含社交互动，会导致 CTR 虚高。

许可证

MIT

参与贡献

欢迎贡献！请：

1. 为新工具添加测试
2. 更新 README，介绍新功能
3. 遵循现有代码风格
4. 发布版本时添加版本标签

支持

• 问题： 在 GitHub issues 中报告 Bug 或提出功能请求
• 文档： 详尽的 API 参考请参阅 docs/ 文件夹
• 社区： 在 GitHub 的讨论区交流

---

作者

Mark Harnett — 需求开发负责人和付费媒体从业者，致力于构建 AI 驱动的广告管理工具。管理多个客户的 LinkedIn 广告系列时，他萌生了打造此服务的想法，希望让 Claude 能够自主处理广告系列运营、效果分析和批量创意更新。

面向生产工作负载构建：具备弹性的 API 调用（熔断器、退避重试、响应截断）、准确的 CTR 计算（使用落地页点击，而非总点击数）和多账户支持。

Mark 的其他作品： mcp-bing-ads -- 提供 10 个工具的 Bing/Microsoft Ads MCP 服务。

最后更新： 2026-03-13