liam-linkedin-ads-MCP

# 利姆 **利姆** 是适用于领英（LinkedIn Ad Manager）的广告管理器。通过与克劳德（MCP）或命令行界面（CLI）对话创建活动。适用于希望从联系人列表和简介中快速创建多个活动，然后自行添加创意图片的营销团队。所有内容都创建为**草稿**，因此在您明确激活活动管理器的活动之前，不会产生任何花费。 > 非官方且不隶属于领英或获得领英的认可或支持。 > 涵盖创建、匹配受众（包括直接从Salesforce建立受众）、转化选择、性能报告/洞察、竞争对手广告情报和变更日志，包含前后提升。有关已发布内容和计划内容的详细信息，请参见 [ROADMAP.md](./ROADMAP.md)。 ## 您可以用它做什么 一旦利姆连接，您就可以用日常语言与您的助手交流。当前可以处理的实际请求，大致按照活动创建的顺序排列： - “美国SaaS公司的需求生成副总裁有多少人可以被触达？”（解析定位条件，估算受众范围，无需花费） - “上传这个CSV文件作为匹配受众。”（自动清理列，哈希电子邮件，转换公司域名为URL） - “从Salesforce建立一个受众：每个标记为目标的账户中的联系人。”（SOQL直接连接到匹配受众） - “为该受众启动一个草稿活动，每天100美元，跟踪演示预订转化。”（活动组 + 活动 + 草稿广告，一次调用） - “HubSpot目前正在运行哪些广告，他们推出了什么优惠？”（读取公共广告库：复制，格式和欧盟定位元数据，适用于任何公司） - “上个月的再定位表现如何，与上个月相比？”（趋势报告，带有差异） - “本周我应该暂停哪些广告？”（账户汇总，显示表现最佳/最差的广告，并标记） - “重写失败广告的复制品。”（删除 + 重新创建为新的草稿；领英忽略对实时广告帖子的编辑） - “新的标题是否真的有帮助？”（变更日志 + 前后提升） 利姆解决细节问题并返回ID。每个功能也是一个`liam` CLI命令，用于脚本或批量使用。 ### 循环运行 利姆中没有调度程序。使用您使用的任何客户端的调度程序。一些有效的循环： - “每周一早上9点，拉取上周的性能摘要，与前一周进行比较，并标记任何超过20%的变化。”（克劳德代码调度的代理） - “每周五，检查我们的三大竞争对手本周发布了哪些新广告，并总结其角度。” - “每隔几小时检查一次受众匹配状态，并在其达到300名成员时通知我。”（匹配受众服务的最低要求） - 或直接跳过助手，将CLI放入cron：`0 9 * * 1 liam report summary -p last_7_days` ## 层次结构映射（领英与谷歌/ Meta不同） | 常用术语 | 领英实体 | 包含内容 | | --- | --- | --- | | 活动 | **活动组** | 状态，总/共享预算 | | 广告组 | **活动** | 定位，预算，出价，时间表，格式 | | 广告 | **创意** | 渲染的广告（`status: DRAFT`） | | 受众 | **DMP分段** | 附加到活动的定位 | ## 软件包 - `@liads/core`：领英REST客户端，OAuth，资源模块，CSV + SHA256哈希，Salesforce读取器。 - `@liads/mcp`：MCP服务器（本地stdio；被托管应用重用）。**主要接口。** - `@liads/cli`：`liam` CLI核心，适用于脚本批量运行。 - `@liads/web`：Next.js应用，托管MCP，基于Vercel的HTTP服务。 ## 工作原理 两个接口都是同一引擎上的薄层。每个MCP工具和CLI命令通过`createLiads()`（`core/src/client.ts`）构建客户端，加载配置和自动刷新OAuth令牌提供程序，然后调用类型化的资源模块（`campaigns.ts`，`audience.ts`，`report.ts`，...），该模块封装了领英的版本化REST API（`LinkedIn-Version`在配置中固定）。输入形状以zod模式存储在`core/src/schemas.ts`中，并原样重用为MCP工具输入模式，因此CLI和MCP永远不会分离。 创建时强制执行仅草稿安全规则：活动组，活动和创意都以`DRAFT`状态写入，并且没有“激活”工具或命令。每条写入记录也会通过一个HTTP检查点，该检查点会追加到本地变更日志（`~/.liads/changelog.jsonl`）中，以便后续的提升分析。 [AGENTS.md](./AGENTS.md)包含完整的架构说明和从实时测试中学习的领英API注意事项（restli编码，必填字段，DMP受众流程）。 ## 安装 有两种方法安装利姆： 1. **[作为MCP服务器安装](#选项1：作为MCP服务器安装)**，与克劳德代码，克劳德桌面，Cursor或任何MCP客户端注册，以便通过与助手对话创建活动。在本地运行，或跳过始终在线的安装，直接使用您的凭证连接到托管端点。 2. **[作为终端CLI安装](#选项2：安装终端CLI)**，一个全局`liam`命令，用于从终端，脚本或cron运行所有内容。 两者都针对**您自己的领英开发者应用**，因此您的凭证和广告账户保持您自己的。第一步和第二步是共享的：创建领英应用（步骤0）和构建+身份验证（步骤1）。之后，选择您的路径，或两者兼而有之；它们读取相同的`~/.liads`凭证。 ### 步骤0：创建领英应用（一次） 1. 在https://www.linkedin.com/developers/apps创建一个应用。它必须与您的领英页面关联。 2. 在**产品**选项卡中，请求访问： | 产品 | 需要用于 | 是否必填 | | --- | --- | --- | | 广告API | 活动，广告，定位，报告，转化 | **是** | | 受众 | 上传CSV联系人/公司列表作为匹配受众 | 仅限上传受众 | | 领英广告库 | 通过官方API获取竞争对手广告元数据 | 可选（浏览器爬虫无需此权限） | 3. 在**身份验证**选项卡中，添加`http://localhost:53682/callback`作为授权重定向URL，并记下您的**客户端ID**和**客户端密钥**。 4. 一旦广告API获得批准，请在**产品→广告API→查看广告账户**下映射您的广告账户。跳过此步骤，`accounts list`将返回为空。 **OAuth范围**。 `liam auth login`请求`rw_ads`（创建和编辑活动），`r_ads_reporting`（报告），`rw_conversions`（转化跟踪）和`w_organization_social`（图像广告创建帖子，所有权归您的领英页面）。如果您稍后添加产品或范围，请再次运行`auth login`;令牌刷新仅保留您最初授予的范围。 ### 步骤1：构建和身份验证（一次，两条路径） 需要git，Node.js 20+和pnpm。 ```bash git clone https://github.com/stan-default/liam.git cd liam pnpm install && pnpm -r build # 应用凭证（或者设置LIADS_CLIENT_ID / LIADS_CLIENT_SECRET环境变量） mkdir -p ~/.liads echo '{ "clientId": "...", "clientSecret": "...", "linkedinVersion": "202605" }' > ~/.liads/config.json node packages/cli/dist/index.js auth login # 打开浏览器；令牌存储在~/.liads node packages/cli/dist/index.js accounts list # 验证，然后在config.json中设置defaultAccountId ``` ### 选项1：作为MCP服务器安装 使用您的MCP客户端注册服务器；它从步骤1读取`~/.liads`凭证。 **克劳德代码** ```bash claude mcp add liam -- node /abs/path/liam/packages/mcp/dist/index.js ``` **克劳德桌面，Cursor或任何MCP客户端**，在其MCP配置JSON中： ```json { "mcpServers": { "liam": { "command": "node", "args": ["/abs/path/liam/packages/mcp/dist/index.js"] } } } ``` 询问只读内容以确认其有效：“列出我的广告账户”或“我的账户在过去30天内表现如何？” #### 主机MCP：使用您自己的凭证连接，无需部署 托管MCP服务器在 ``` https://liam-mcp.vercel.app/api/mcp ``` 是**多租户，带您自己的凭证**：您传递领英开发应用的凭证作为请求头，每次调用都针对**您的**应用和**您的**广告账户运行。服务器不保留您的任何状态：凭证在内存中用于调用领英，不会记录或持久化。 | 头部 | 值 | 是否必填 | | --- | --- | --- | | `X-Liads-Client-Id` | 您的领英应用的客户端ID | 是 | | `X-Liads-Client-Secret` | 您的领英应用的客户端密钥 | 是 | | `X-Liads-Refresh-Token` | 从您的`auth login`刷新令牌（~365d） | 是 | | `X-Liads-Account-Id` | 调用省略时使用的数字广告账户ID | 否 | | `X-Liads-Linkedin-Version` | API版本固定（YYYYMM），默认为服务器版本 | 否 | 执行步骤0和步骤1（领英应用和本地`auth login`; 领英的OAuth同意必须在您的浏览器中发生，以便令牌铸造是本地步骤之一）。然后打印准备好的连接命令： ```bash node packages/cli/dist/index.js auth export --mcp # claude mcp add --transport http liam https://liam-…vercel.app/api/mcp \ # --header "X-Liads-Client-Id: …" \ # --header "X-Liads-Client-Secret: …" \ # --header "X-Liads-Refresh-Token: …" \ # --header "X-Liads-Account-Id: …" ``` 任何支持自定义头的MCP客户端都可以使用这种方式（对于没有原生HTTP传输的客户端：`npx mcp-remote <url> --header "X-Liads-Client-Id: …" …`）。通过只读调用验证（“列出我的广告账户”），从那时起连接只是带有头的URL，可在从未克隆此存储库的机器上使用。 了解权衡：您的客户端密钥和刷新令牌随每个请求到该服务器，因此请仅指向您信任的部署，或自行托管相同的端点（下一节）。范围可以管理广告但永远不会激活；仅在工具层中强制执行草稿规则。 托管限制（全部设计如此，需要本地资源）：`upload_audience_csv`读取服务器上的CSV路径，`audience_from_salesforce`需要您的本地`sf` CLI，竞争对手广告抓取回退到仅API的元数据（无浏览器），变更日志/提升工具需要本地`~/.liads/changelog.jsonl`。通过本地MCP服务器或CLI运行这些。 **在上面添加技能**。干净的团队分工：您的MCP客户端配置保存凭证（上面的头部），小型技能或系统提示保存您的剧本：默认广告账户，命名约定，固定排除，诸如“受众扩展始终关闭”之类的规则。 [`skills/`](./skills)文件夹中的存储库是一个示例；复制一个，替换您的默认值，您的助手使用您的规则驱动托管工具。凭证永远不应位于技能文件中。 #### 在Vercel上自行托管相同的端点 运行您自己的实例，以便凭证永远不会触及共享基础设施，并且您还可以获得私有环境配置的租户： 1. 获取您的环境变量：`node packages/cli/dist/index.js auth export`。 2. 将`apps/web`部署到Vercel（将项目**根目录**设置为`apps/web`）。 3. 在Vercel项目设置中，添加环境变量`.env.example`（`LIADS_CLIENT_ID`，`LIADS_CLIENT_SECRET`，`LIADS_REFRESH_TOKEN`，`LIADS_LINKEDIN_VERSION`和一个强大的`MCP_AUTH_TOKEN`）。在Vercel的部署保护设置中，禁用Vercel身份验证以进行生产（或添加保护-绕过秘密）；否则，MCP客户端无法访问端点。 4. 您的MCP端点是`https://<your-app>.vercel.app/api/mcp`。使用其中的机密连接： ```bash claude mcp add --transport http liam https://<your-app>.vercel.app/api/mcp \ --header "Authorization: Bearer <MCP_AUTH_TOKEN>" ``` 请求携带`MCP_AUTH_TOKEN`使用环境凭证（您的租户）。携带上述`X-Liads-*`头的请求使用调用者的凭证，因此一个自托管实例可以为您的整个团队服务，每个成员都在他们自己的领英应用上。 ### 选项2：安装终端CLI 步骤1已经留下一个可用的CLI在`node packages/cli/dist/index.js`。要获得全局`liam`命令而不是长的`node`路径： ```bash cd packages/cli && pnpm link --global liam accounts list ``` （无pnpm link？别名也行：`alias liam="node /abs/path/liam/packages/cli/dist/index.js"`。） 一个合理的会话： ```bash liam targeting search titles "demand generation" # 解析定位URN liam report summary -p last_30_days # 账户汇总 + 标志 liam launch --brief examples/brief.json # 只创建草稿 ``` 完整的 [CLI参考](#cli-reference) 在下面。 ### 或粘贴此提示，让您的助手完成设置 将整个块复制到克劳德（或任何具有终端访问权限的合格助手）并让它一步一步地引导您完成上述所有操作： ```text 您正在帮助我设置利姆（Liam），这是一个开源的领英广告管理器，来自 https://github.com/stan-default/liam。它在本地运行为MCP服务器和CLI。 它在领英上创建的所有内容都是草稿，因此在Campaign Manager中激活之前不会花费任何费用。 引导我完成设置，一步一步。您可以运行我可以运行的命令， 显示我需要点击的位置，如果不能显示，请准确告诉我应该点击哪里，并等待我的确认后再继续。 1. 检查git、Node.js 20或更高版本以及pnpm是否已安装。帮助我安装 任何缺失的内容。 2. 克隆 https://github.com/stan-default/liam 并在存储库根目录运行“pnpm install”然后 “pnpm -r build”。 3. 帮助我在 https://www.linkedin.com/developers/apps 创建领英开发者应用（它必须与我的 领英页面关联）： a. 在“产品”选项卡中，请求访问“广告API”产品。 这是唯一必需的产品；批准可能需要一段时间。 b. 可选：也可以请求“Audiences”，如果我想上传CSV联系人或 公司列表作为匹配受众。 c. 可选：也可以请求“LinkedIn Ad Library”，如果我想要竞争对手广告 通过官方API的元数据。 d. 在“身份验证”选项卡中，添加 http://localhost:53682/callback 作为授权 重定向URL，并显示我的客户端ID和客户端密钥的位置。 4. 创建~/.liads/config.json，其中包含我的clientId、clientSecret和 “linkedinVersion”: “202605”。 5. 运行“node packages/cli/dist/index.js auth login”。我的浏览器打开领英的 同意屏幕；我批准后，令牌存储在~/.liads/credentials.json中。 6. 验证“node packages/cli/dist/index.js accounts list”。如果没有 显示帐户，请提醒我到开发者门户下的Products > Advertising API > View Ad Accounts映射我的广告账户。然后将我的账户ID设置为 ~/.liads/config.json中的“defaultAccountId”。 7. 使用我使用的MCP客户端注册MCP服务器： - 克劳德代码：claude mcp add liam -- node <abs repo path>/packages/mcp/dist/index.js - 克劳德桌面或其他客户端：添加{"command": "node", "args": ["<abs repo path>/packages/mcp/dist/index.js"]}下的mcpServers配置中。 8. 确认工具加载，然后显示一个只读调用以确认，例如 list_ad_accounts或last_30_days的性能摘要。 如果任何步骤失败，请显示确切的错误并帮助我解决它，然后再继续下一步。 ``` ## 工具列表 - **账户：** `list_ad_accounts` - **定位：** `list_targeting_facets`，`search_targeting`（输入 facet 进行实体 URN 的预先搜索）， `list_facet_entities`，`estimate_audience`（结构化规范）。用简单的语言交流 （“美国 SaaS 公司需求生成副总裁”），Liam 解析 facet 并在创建活动前估计覆盖范围。 - **受众：** `upload_audience_csv`（自动清理 CSV：规范列名，删除非匹配列，哈希电子邮件， 将公司域名转换为网站网址；支持联系人和公司列表），`audience_from_salesforce`（SOQL 到匹配受众），`get_audience_status` - **转化：** `list_conversions`（选择现有的洞察标签转化来跟踪）。 `create_campaign` 和 `launch_from_brief` 接受 `conversionIds` 或 `conversionName`，并 默认为配置中的 `defaultConversionName`。 - **活动：** `create_campaign_group`，`create_campaign`，`create_text_ad`，`create_image_ad`； `list_campaigns`（账户结构：活动组及其广告组，**包括草稿**，与报告不同，报告仅显示有支出实体的活动），`list_ads`，`delete_ad` （删除创意和尽力而为的直接赞助内容帖子）。LinkedIn 的编辑器忽略实时广告的帖子编辑，因此要更改副本，请重新创建：`delete_ad` + `create_image_ad`。 - **协调器：** `launch_from_brief`（受众 + 群组 + 活动 + 草稿创意一步到位） - **报告：** `performance_summary`（账户汇总 + 顶部/底部 + 标志），`get_performance` （每个实体的 KPI 在任何级别），`performance_trend`（每周/每月带有增量）。KPI：点击率， 每点击成本，每千次展示成本，每次转化成本，转化率。级别：活动组，活动，创意。 - **竞争对手情报：** `inspect_competitor_ads` 从 LinkedIn 广告库中读取任何公司的广告（无需广告账户访问权限）。 **官方广告库 API** （`GET /rest/adLibrary`，需要“LinkedIn 广告库”产品授权）返回结构化元数据（广告商，付款人， 格式和欧盟提供的广告运行日期，展示范围，每个国家/地区的划分和定位方面），但不包括创意。 **Playwright 刮刀** 公共库提供广告副本/图像。引擎（`engine`）：`api`（仅元数据，快速，托管有效），`scraper`（通过浏览器，本地，支持公司 ID），和 `auto`（默认：API 元数据加上每个广告详情页的副本分层，如果 API 未配置则回退到刮刀）。按`广告商`名称或`关键词`（API 没有公司 ID 或日期筛选器）搜索。 CLI：`liam competitor ads`。 ### 定位规范 结构化定位使用映射到实体 URN 的短 facet 名称（使用 `search_targeting` 解析 URN）。facet 内的 URN 为 OR；facet 为 AND；排除的 facet 为 OR。 ```json { "include": { "locations": ["urn:li:geo:103644278"], "seniorities": ["urn:li:seniority:7"], "titles": ["urn:li:title:26587"] }, "exclude": { "industries": ["urn:li:industry:47"] } } ``` ## CLI 参考 所有命令也可以通过 `node packages/cli/dist/index.js <cmd>` 使用。 ``` liam auth login # OAuth，存储令牌在 ~/.liads liam auth export # 打印自托管服务器（Vercel）的环境变量 liam auth export --mcp # 打印托管 MCP 连接命令以及您的头部 liam accounts list # 列出可访问的广告账户 liam targeting search <facet> <query> # 输入 facet 进行实体 URN 的预先搜索 liam targeting estimate <facet> <urns…> # 某个 facet 的 URN 的受众规模 liam audience upload -n <name> -f <csv> # 清理 + 上传 CSV 为匹配受众 liam audience upload -n <name> -f <csv> --dry-run # 预览清理后的 CSV，无上传 liam audience from-salesforce -n <name> -q "<SOQL>" # Salesforce 查询 -> 匹配受众 liam audience status <segmentId> # 匹配状态 + 已解决规模 liam conversions list # 账户转化（选择一个跟踪） liam campaigns list [--group <id>] [--all] # 活动组 + 广告组，包括草稿 liam ad list <campaignId> # 广告组中的广告（ID，状态，名称），包括草稿 liam ad delete <creativeId> # 删除广告（创意 + 其直接赞助内容帖子） liam report summary [-p <period>] # 账户汇总：总数，表现最佳，标志 liam report perf <level> [--parent <id>] # 每个实体的 KPI 行 liam report trend <level> <id> [-b weekly|monthly] # 趋势与增量 liam launch --brief <brief.json> # 受众 + 群组 + 活动 + 草稿创意 liam competitor ads <advertiser> # 任何公司的广告来自公共广告库 # <advertiser> = 名称，公司 ID 或公司网址 # -k <keyword> -c <countries> -e auto|api|scraper -m <max> --json liam changelog list [-t <type>] [-i <id>] # 记录的广告更改，最新的优先 liam changelog add -t <type> -i <id> -f <field> --after <v> [-l <label>] # 记录其他地方进行的更改 liam lift <level> <id> [-w <days>] # 每个记录更改的前后表现 ``` 时间段：`last_7_days`，`last_30_days`，`last_90_days`，`month_to_date`，`last_month`。 `--account` 默认情况下，如果适用，默认为配置中的 `defaultAccountId`。 ## 变更日志和提升 Liam 保留每次对广告实体的更改的追加日志，以便您可以衡量更改的**提升**：性能在更改前后的窗口中如何不同。 - **存储位置：** `~/.liads/changelog.jsonl`（每行一个 JSON 对象）。一个普通的本地文件，无需设置。可以使用 `LIADS_CHANGELOG_PATH` 覆盖路径。 - **自动捕获：** Liam 对活动组，活动或创意进行的每次创建/更新操作都会自动记录（在单个 HTTP 阻塞点捕获，因此不会被遗忘）。 - **手动条目：** 记录在 Liam 之外进行的更改（例如，在活动管理器中），或附加假设，使用 `liam changelog add` / `log_ad_change` 工具。使用 `-l/--label` 为测试命名（例如 `"outcome-led headline test"`），使用 `--tags` 对相关更改进行分组。 - **提升：** `liam lift <level> <entityId>` （或 `compute_lift`）读取该实体的日志，并对于每个更改，比较 `--window` 天之前（默认为 14）与之后相同的窗口，报告更改前后的 KPI 和每个指标的增量（点击率，每点击成本，转化率，每次转化成本...）。最近的更改会获得一个受限的，部分“之后”的窗口。 这是 **方向性的前后比较，而不是受控实验**。它受到季节性，LinkedIn 编辑后的学习阶段和任何并发预算更改的影响，因此请将增量视为信号。设置 `LIADS_NO_CHANGELOG=1` 以禁用自动捕获； journaling 在托管部署（只读文件系统）上也被禁用。 ## 配置 本地配置存储在 `~/.liads/config.json`（模式 0600，永远不在仓库中）： | 字段 | 用途 | | --- | --- | | `clientId`，`clientSecret` | LinkedIn 应用凭证（或 `LIADS_CLIENT_ID`/`LIADS_CLIENT_SECRET`） | | `linkedinVersion` | 固定的 API 版本，例如 `202605` | | `defaultAccountId` | 命令/简介省略时使用的广告账户 | | `defaultConversionName` | 未指定时为新活动选择的默认转化 | | `mcpAuthToken` | 托管 MCP 端点的承载令牌 | 托管等效项是 `LIADS_*` 环境变量和 `MCP_AUTH_TOKEN`（请参见 `.env.example`）。 OAuth 令牌存储在 `~/.liads/credentials.json` 中。 ## Salesforce 集成 Liam 通过 shelling 到身份验证的 `sf` CLI（`sf data query`）读取 Salesforce，因此它重用现有的登录并且不需要新的凭证。`audience_from_salesforce`（和 `liam audience from-salesforce`）采用一个 SOQL 查询，该查询选择一个电子邮件列，并将结果转换为匹配的受众，从而从“Salesforce 中标记的账户”到“LinkedIn 定位”形成一个闭环。示例： ``` liam audience from-salesforce -n "Q3 target accounts" \ -q "SELECT Email FROM Contact WHERE Account.Target_List__c = true AND Email != null" ``` ## 安全 - 每个活动/创意都创建为 **草稿/暂停**。激活是一个单独的明确步骤。 - 匹配受众的匹配需要最多 48 小时，并且活动需要约 300 个匹配成员才能投放。 - LinkedIn 不公开显示人级别的广告查看数据；交叉引用是在账户/分段级别进行的。 - 机密信息永远不会进入仓库。本地：`~/.liads`。托管：Vercel 环境变量。 ## 许可证 MIT