内容
# LINE 广告 MCP 服务器
> 由 **Praphat Srisuma (Ong)** · [Spark Factor Co., Ltd.](https://sparkth.io) · LINE 认证教练构建
> 在 [Apache 2.0](LICENSE) 下许可 — 需要署名，参见 [NOTICE](NOTICE)
MCP 服务器，用于 Claude 直接调用 LINE 广告 API v3，代替在 API 可以完成的任务中控制浏览器，如报告、广告活动/广告组/广告管理以及受众管理。
---
## ⚡ 使用 Claude Cowork（最简单的方法）
无需手动输入命令 — 只需将以下提示复制到 **Claude Desktop（Cowork 模式）**，然后让 Claude 完成所有操作：
```
请帮助我设置 LINE 广告 MCP 服务器。
步骤：
1. 克隆仓库：https://github.com/ongkub/line-ads-mcp.git
- 推荐路径，如 ~/line-ads-mcp 或 ~/Desktop/line-ads-mcp
- 如果文件夹已存在，请改为 git pull
2. 安装依赖：
cd <克隆路径>
python3 -m venv .venv
source .venv/bin/activate # Windows：.venv\Scripts\activate
pip install -e .
3. 从 .env.example 创建 .env 文件：
cp .env.example .env
- 然后询问我 LINE_ADS_ACCESS_KEY、LINE_ADS_SECRET_KEY、LINE_ADS_AD_ACCOUNT_ID 是什么
- （可在 LINE Ads 管理员后台找到 → 设置 → API 管理）
- 将这些值填充到 .env 文件中
4. 更新 claude_desktop_config.json 以添加 MCP 服务器块：
{
"mcpServers": {
"line-ads": {
"command": "<.venv/bin/python 的绝对路径>",
"args": ["-m", "line_ads_mcp.server"],
"cwd": "<仓库的绝对路径>",
"env": {
"LINE_ADS_ACCESS_KEY": "<从 .env>",
"LINE_ADS_SECRET_KEY": "<从 .env>",
"LINE_ADS_AD_ACCOUNT_ID": "<从 .env>"
}
}
}
}
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json
- 如果文件已存在 mcpServers，请添加 "line-ads"，不要覆盖原有内容
5. 告诉我是否成功，以及是否需要退出并重新打开 Claude Desktop 以加载 MCP
在执行过程中，如果需要任何信息，请逐一询问
```
> **注意：** 在 Claude Cowork 完成后，您需要 **退出并重新打开 Claude Desktop** （不是简单地关闭窗口），以便加载新的 MCP 服务器。
### 最后一个步骤 - 设置系统提示
重启后，在 Claude Desktop 中创建一个新的 **项目** → **项目说明** → 复制 [`CLAUDE_PROJECT_PROMPT.md`](CLAUDE_PROJECT_PROMPT.md) 的全部内容。
就这样，您现在可以使用了。
---
### 使用 Claude Cowork 更新到新版本
当 GitHub 上有更新时，请使用以下提示：
```
请帮助我更新 LINE 广告 MCP 服务器。
仓库位于：https://github.com/ongkub/line-ads-mcp.git
机器上的文件夹位于：<路径>
按照步骤：
1. cd 进入文件夹
2. git pull --rebase origin main
3. source .venv/bin/activate && pip install -e .
4. python -m pytest （如果测试失败，请通知我）
5. 通知我需要退出并重新打开 Claude Desktop
```
---
## 对于营销人员 - 通过 AI 使用
无需编写代码，无需每次打开 LINE Ads 管理后台 — 只需与 AI 交谈，让它代表您提取数据和管理广告活动。
### 在 Claude Desktop 上使用（推荐）
Claude Desktop 直接支持 MCP，设置一次即可使用。
**步骤：**
1. **安装 Python 和此仓库**
```bash
git clone https://github.com/ongkub/line-ads-mcp.git
cd line-ads-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
```
2. **在 `.env` 中设置凭证**
```bash
cp .env.example .env
# 编辑 .env 文件，添加来自 LINE Ads 管理后台的访问密钥/秘密密钥
# （设置 → API 管理）
LINE_ADS_ACCESS_KEY=您的访问密钥
LINE_ADS_SECRET_KEY=您的秘密密钥
LINE_ADS_AD_ACCOUNT_ID=A_xxxxxxxxxxxx
```
3. **在 Claude Desktop 中添加 MCP 服务器**
打开 Claude Desktop 的配置文件：
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\Claude\claude_desktop_config.json`
添加以下块：
```json
{
"mcpServers": {
"line-ads": {
"command": "/绝对路径/to/.venv/bin/python",
"args": ["-m", "line_ads_mcp.server"],
"cwd": "/绝对路径/to/line-ads-mcp",
"env": {
"LINE_ADS_ACCESS_KEY": "您的密钥",
"LINE_ADS_SECRET_KEY": "您的秘密",
"LINE_ADS_AD_ACCOUNT_ID": "A_xxxxxxxxxxxx"
}
}
}
}
```
4. **重启 Claude Desktop 即可使用**
5. **设置系统提示（重要）** - 以便 Claude 自动了解角色和安全规则。
进入 Claude Desktop → 创建新的 **项目** → **项目说明** → 复制 [`CLAUDE_PROJECT_PROMPT.md`](CLAUDE_PROJECT_PROMPT.md)
**在设置完成后在 Claude 中的示例：**
```
请查看所有正在运行的广告活动。
```
```
总结过去 7 天的业绩，哪个广告活动的 CPF 最低。
```
```
暂时停止广告活动“添加好友：...”。
```
---
### 在 Gemini CLI 上使用
Gemini CLI 通过 `settings.json` 文件或 `gemini mcp add` 命令支持 MCP 服务器。
**基本步骤：**
1. **安装仓库和依赖**
```bash
git clone https://github.com/ongkub/line-ads-mcp.git
cd line-ads-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
```
2. **在 `.env` 中设置凭证**
```bash
LINE_ADS_ACCESS_KEY=您的访问密钥
LINE_ADS_SECRET_KEY=您的秘密密钥
LINE_ADS_BASE_URL=https://ads.line.me/api/v3
LINE_ADS_AD_ACCOUNT_ID=A_xxxxxxxxxxxx
```
3. **为 Gemini CLI 添加 MCP 服务器**
使用命令：
```bash
gemini mcp add line-ads \
-e LINE_ADS_ACCESS_KEY=您的访问密钥 \
-e LINE_ADS_SECRET_KEY=您的秘密密钥 \
-e LINE_ADS_BASE_URL=https://ads.line.me/api/v3 \
-e LINE_ADS_AD_ACCOUNT_ID=A_xxxxxxxxxxxx \
/绝对路径/to/line-ads-mcp/.venv/bin/python \
-m line_ads_mcp.server
```
命令完成后，请检查 `settings.json` 以确保 `cwd` 指向正确的仓库。
或编辑 `~/.gemini/settings.json` / `.gemini/settings.json` 文件：
```json
{
"mcpServers": {
"line-ads": {
"command": "/绝对路径/to/line-ads-mcp/.venv/bin/python",
"args": ["-m", "line_ads_mcp.server"],
"cwd": "/绝对路径/to/line-ads-mcp",
"env": {
"LINE_ADS_ACCESS_KEY": "您的密钥",
"LINE_ADS_SECRET_KEY": "您的秘密",
"LINE_ADS_BASE_URL": "https://ads.line.me/api/v3",
"LINE_ADS_AD_ACCOUNT_ID": "A_xxxxxxxxxxxx"
},
"timeout": 600000,
"trust": false
}
}
}
```
4. **检查 Gemini 是否识别 MCP 工具**
```bash
gemini
/mcp
```
应该会看到名为 `line-ads` 的服务器和 `list_campaigns`、`get_report`、`create_campaign` 等工具。
5. **为 Gemini 设置说明**
在开始会话时，粘贴：
```text
请阅读 CLAUDE_PROJECT_PROMPT.md、AGENTS.md 和相关的 workflow/knowledge，然后再调用 LINE Ads MCP 工具。
每次写入操作必须先设置为 dry_run=True，除非收到“确认”指令，否则不得设置为 dry_run=False。
请勿假设货币价值，如预算、出价上限、CPF、CPC、CPA。
```
**Gemini CLI 示例：**
```text
使用 LINE Ads MCP 拉取所有活跃的广告活动，并总结最近 7 天的业绩。
```
```text
我需要创建一个添加 LINE OA 好友的广告活动，采用 MCP 手动/API 优先的方式。
请先阅读 workflow/02-campaign.md，然后逐一询问所需信息。
```
参考文献：[Gemini CLI MCP 服务器文档](https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html)
---
### 在 OpenAI Codex 上使用（适用于技术团队/系统管理员）
[Codex](https://codex.com) 是 OpenAI 的 AI 编程代理，可以直接运行 Python 代码。
无需通过 MCP 协议 — Codex 导入工具并直接调用。
**步骤：**
1. **打开 Codex 并将此仓库克隆到环境中**
```bash
git clone https://github.com/ongkub/line-ads-mcp.git
cd line-ads-mcp
pip install -e .
```
2. **设置 `.env` 文件** 与 Claude Desktop（步骤 2）类似
3. **告诉 Codex 您要执行的操作**，例如：
```
拉取所有广告活动并总结最近 7 天的业绩。
```
```
创建一个广告活动，预算为 300 泰铢/天，并显示 payload 以供确认。
```
Codex 将从 `src/line_ads_mcp/tools/` 导入工具并直接调用。
安全规则 `dry_run=True` 仍然有效。
---
### 营销人员的安全性
- **所有与资金相关的操作**（创建广告活动、设置预算、创建广告）**在发送前始终会显示预览** - AI 必须在发送前获得确认。
- **没有删除按钮** - 此套件中没有用于删除广告活动/广告组/广告的工具。
- 凭证存储在您本地机器上的 `.env` 文件中，而不是通过外部服务器。
---
## 设置
```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env
```
设置 `.env` 文件：
```bash
LINE_ADS_ACCESS_KEY=您的访问密钥
LINE_ADS_SECRET_KEY=您的秘密密钥
LINE_ADS_BASE_URL=https://ads.line.me/api/v3
LINE_ADS_AD_ACCOUNT_ID=A_xxxxxxxxxxxx
```
## 从 Git 更新
当 GitHub 上有新版本时，您需要将其拉取到本地。
### 如果没有本地文件修改
```bash
cd /路径/to/line-ads-mcp
git status
git pull --rebase origin main
source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest
```
如果使用此路径：
```bash
cd "/Users/ongkub/Desktop/lineads-ai/LINE Ads V0.1.3 - MCP Layer"
git pull --rebase origin main
source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest
```
### 如果有本地文件修改
先检查：
```bash
git status
```
如果有未提交的修改：
```bash
git stash push -m "本地工作在更新前"
git pull --rebase origin main
git stash pop
python -m pytest
```
如果 `git stash pop` 后有冲突，请解决冲突文件并运行：
```bash
git status
python -m pytest
```
### 不应被覆盖的文件
- `.env` 文件不应提交，也不应从 Git 覆盖。
- 访问密钥/秘密密钥等凭证应仅存储在 `.env` 文件或 AI 客户端的配置中。
- 如果 `.env.example` 文件有变更，请比较后将新密钥添加到 `.env` 文件中。
## 运行
```bash
python -m line_ads_mcp.server
```
或使用控制台脚本：
```bash
line-ads-mcp
```
## Claude Desktop 配置
```json
{
"mcpServers": {
"line-ads": {
"command": "python",
"args": ["-m", "line_ads_mcp.server"],
"cwd": "/Users/ongkub/Desktop/lineads-ai/LINE Ads V0.1.3 - MCP Layer",
"env": {
"LINE_ADS_ACCESS_KEY": "您的密钥",
"LINE_ADS_SECRET_KEY": "您的秘密",
"LINE_ADS_AD_ACCOUNT_ID": "A_xxxxxxxxxxxx"
}
}
}
}
```
## 安全性
- 没有删除工具
- 写入工具默认 `dry_run=true`
- 预算/出价变更必须由助手请求用户确认，然后再调用 `dry_run=false`
- 凭证仅从环境变量读取，不在代码中硬编码。
- 错误消息以中文返回，以便助手可以直接传递给用户。
## 工具状态
### ✅ 已准备好读取（与真实 API 进行烟雾测试）
| 工具 | 备注 |
|---|---|
| `list_campaigns` | ✅ |
| `list_adsets` | ✅ |
| `list_ads` | ✅ |
| `get_ad_status` | ✅ |
| `get_report` / `get_daily_report` / `get_weekly_report` | ✅ |
| `list_audiences` | ✅ |
| `list_advanced_targeting_codes` | ✅ 使用官方兴趣/行为/状态代码 |
### ✅ 已准备好写入（有效载荷符合规范 + 测试通过 - 默认为 `dry_run=true`）
| 工具 | 预算/出价 | 目标/状态 | 备注 |
|---|---|---|---|
| `create_campaign` | `dailyBudgetMicro` / `totalBudgetMicro`（THB × 1M） | `campaignObjective: GAIN_FRIENDS` | 必须始终指定 `start_date`，例如 `2026-05-14T09:00:00+07:00` |
| `update_campaign` | `dailyBudgetMicro` | `configuredStatus` | |
| `pause_campaign` / `resume_campaign` | — | `configuredStatus: PAUSED/ACTIVE` | |
| `create_adset` | `dailyBudgetMicro` / `bidAmountMicro`（THB × 1M） | `bidType`、`bidStrategy` required | 如果有 `interest_codes`，则使用 `targetingMode=MANUAL` + `includeAdvancedTargetings` |
| `update_adset` | `dailyBudgetMicro` / `bidAmountMicro` | `configuredStatus` | |
| `pause_adset` / `resume_adset` | — | `configuredStatus: PAUSED/ACTIVE` | |
### ✅ 已准备好写入 - 有效载荷已从真实 API 响应和错误探测中验证
| 工具 | 备注 |
|---|---|
| `create_ad` | 创意为嵌套对象；使用 `imageHash`（来自 `upload_media`）、`title`、`callToAction.type`；`title`/`description` 不超过 20 个字符 |
| `upload_media` | 端点 `/media/upload`；必须发送 `mediaType: IMAGE\|VIDEO`；签名使用 `"multipart/form-data"` |
### ⚠️ 仅限 dry-run（403 权限 - 代码正确，但账户未开启功能）
| 工具 | 状态 |
|---|---|
| `create_audience` | API 返回 403 对所有类型 - 必须在 LINE Ads 管理后台开启自定义受众功能 |
## 预算和出价单位
LINE Ads API v3 对所有货币使用 **微** 单位：
```
1 THB = 1,000,000 微
真实广告组的示例：
dailyBudgetMicro: 300_000_000 → 300 THB/天
bidAmountMicro: 10_000_000 → 10 THB/好友
```
工具接受常规的 THB 值（浮点数），并通过 `common.py` 中的 `to_micro()` 自动转换为微。
## 兴趣定位
LINE Ads API 不接受直接的兴趣名称，如 `Marketing`、`Branding`、`Advertising`、`Business`。必须使用官方代码。
使用 [knowledge/interest-catalog-INDEX.md](knowledge/interest-catalog-INDEX.md) 作为本地缓存的第一层，以节省 token/API 调用。然后仅在需要时加载 `knowledge/interest-detail-*.md`，或在缓存中没有分段、目标/国家/地区/语言更改、API 拒绝代码或需要最新受众规模时调用 `list_advanced_targeting_codes`。
对于已测试的 `TH + GAIN_FRIENDS`：
```
职业和商业 = 代码 "4"
```
使用 `interest_codes` 进行广泛的兴趣：
```json
{
"targeting": {
"targetingMode": "MANUAL",
"ageMin": 25,
"ageMax": 44,
"country": "TH",
"excludedCustomAudienceIds": ["5343822743474"],
"includeAdvancedTargetings": [
{ "interests": ["4"] }
]
}
}
```
如果要缩小受众范围，请使用 `interest_groups`，例如 `[[ "4" ], [ "12" ]]` 在 `includeAdvancedTargetings` 中创建多个对象：
```json
"includeAdvancedTargetings": [
{ "interests": ["4"] },
{ "interests": ["12"] }
]
```
如果 `targetingMode=AUTO`，则不使用兴趣/自定义高级定位。
## 有效的广告活动目标
```
GAIN_FRIENDS ← 添加 LINE OA 好友（来自真实 API 的确认）
WEBSITE_TRAFFIC ← 访问网站
CONVERSIONS
REACH
APP_INSTALL
VIDEO_VIEW
```
> ⚠️ `FRIEND_ADDED`、`VISIT_MY_WEBSITE`、`APP_INSTALLS`、`VIDEO_VIEWS` 是旧的错误枚举 - 工具将立即拒绝。
## 致谢
本项目使用 AI 编程代理作为开发过程的一部分：
- **OpenAI Codex（o3）** - 主框架、身份验证层、工具架构
- **Anthropic Claude** - 有效载荷验证、API 探测、测试套件
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器