内容
# telegram-ads-mcp
一个 [MCP](https://modelcontextprotocol.io) 服务器，允许 AI 代理（Cursor，Claude Desktop 等）读取和管理您的 [Telegram Ads](https://ads.telegram.org) 广告活动 — 列出账户和广告，读取统计数据和预算，并创建/更新广告、CPM、状态和预算 — 通过 Playwright 驱动真实的 ads.telegram.org 网页界面，并使用重用的、基于 cookie 的登录会话。
> **⚠️ 安全警告**
>
> 该服务器重用保存的 Telegram Ads 浏览器会话（`auth_state.json`）。该文件等同于您的 ads.telegram.org 登录凭证 — 任何人都可以像您一样操作，包括花费您的 TON 广告预算。永远不要提交它、共享它或将其检入版本控制。变异和金融工具（`update_ad`、`set_cpm`、`set_status`、`increase_budget`、`set_budget`、`create_ad`、`get_ad_stats_csv`）默认为安全的 `confirm=False` 预览模式，只有在代理显式传递 `confirm=True` 时才生效。请在将此服务器连接到您不完全信任的任何代理之前阅读 [SECURITY.md](SECURITY.md)。
## 要求
- Python 3.11+
- Chromium，通过 Playwright 安装（`playwright install chromium`）
- 一个具有 [ads.telegram.org](https://ads.telegram.org) 访问权限的 Telegram Ads 账户
## 快速开始（推荐：克隆）
克隆和安装在虚拟环境中是推荐的方法 — 它使得一次性交互式登录步骤和 Playwright 浏览器安装变得简单和可复制。
```bash
git clone https://github.com/Free-cat/telegram_ads_mcp.git
cd telegram_ads_mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
playwright install chromium
telegram-ads-auth
```
`telegram-ads-auth` 打开一个真实的（可见的）浏览器窗口，您可以在其中登录 Telegram，选择要管理的广告账户，并保存会话。它打印保存到的路径（默认为 `~/.config/telegram-ads-mcp/auth_state.json`）。
### Cursor 配置
将服务器添加到您的 `mcp.json` 中，使用您刚刚创建的虚拟环境中控制台脚本的 **绝对路径**：
```json
{
"mcpServers": {
"telegram-ads": {
"command": "/ABS/PATH/telegram_ads_mcp/.venv/bin/telegram-ads-mcp",
"env": {
"TELEGRAM_ADS_ACCOUNT": "Artem",
"TELEGRAM_ADS_AUTH_STATE": "/ABS/PATH/to/auth_state.json"
}
}
}
}
```
在添加此配置后重启 Cursor（或重新加载 MCP 服务器）。相同的配置格式适用于 Claude Desktop 的 `claude_desktop_config.json`。
## 替代方法：通过 pip + git 安装
如果您不想克隆，可以直接从 git 安装：
```bash
pip install "git+https://github.com/Free-cat/telegram_ads_mcp.git"
playwright install chromium
```
在您安装软件包的相同环境/解释器中运行 `playwright install chromium`，以便浏览器二进制文件在运行时可用。短暂的环境（例如，通过 `uvx` 每次调用）由于这个原因而很脆弱 — Playwright 需要其浏览器二进制文件在运行之间持久化 — 这就是为什么上述克隆 + 虚拟环境路径对于任何超出快速尝试的方法都是推荐的。
## 工具
所有变异/金融工具默认为 `confirm=False`，返回结构化的预览结果并且不进行任何更改。传递 `confirm=True` 以实际执行操作。
| 工具 | 类型 | 需要 `confirm`？ | 描述 |
|------|------|----------------------|--------------|
| `list_accounts` | 读取 | — | 列出此登录会话可用的 Telegram Ads 账户 |
| `list_ads` | 读取 | — | 列出所有广告，包含完整的表格列（id、指标、预算、状态、日期） |
| `get_ad_info` | 读取 | — | 读取广告表单字段（定位芯片仅对现有广告只读） |
| `get_account_budget` | 读取 | — | 读取 `/account/budget` 上的仅读每个广告预算 |
| `update_ad` | 写入 | 是（保存） | 更新广告信息字段（标题、文本、网址、预算等），不包括 CPM/预算增量 |
| `set_cpm` | 写入 | 是（执行） | 通过 `/edit_cpm` 模态窗口设置 CPM |
| `set_status` | 写入 | 是（执行） | 通过 `/edit_status` 模态窗口设置广告状态（活动 / 暂停） |
| `increase_budget` | 写入（金融） | 是（执行） | 增加广告预算的 TON（增量） |
| `set_budget` | 写入（金融） | 是（执行） | 通过计算当前预算的增量来设置目标预算 |
| `create_ad` | 写入（金融） | 是（执行） | 创建新广告；默认情况下清除草稿 |
| `get_ad_stats_csv` | 写入（下载） | 是（执行） | 下载广告和指定时间段的统计数据 CSV |
每个工具在存储的会话不再有效时都会引发稳定的 `AUTH_EXPIRED` 错误 — 重新运行 `telegram-ads-auth` 以刷新它。
## 配置
| 环境变量 | 目的 |
|---------|---------|
| `TELEGRAM_ADS_AUTH_STATE` | 保存的 Playwright 会话文件的绝对路径。覆盖默认查找（`~/.config/telegram-ads-mcp/auth_state.json`，回退到当前目录中的 `./auth_state.json`）。 |
| `TELEGRAM_ADS_ACCOUNT` | 与 Telegram Ads "选择账户"屏幕上显示的账户名称的子字符串匹配，用于选择要操作的账户的广告。登录账户只有一个账户时可选；多个账户可用时必填。 |
## 限制
- **手动充值碎片。** 服务器可以读取每个广告的预算，但不通过 Fragment 自动添加 TON。
- **广告计划和其他小部件无法自动化。** ads.telegram.org 上的广告计划和"相似频道/机器人"定位小部件超出了 v0.1 的范围。
- **现有广告的定位仅读。** `get_ad_info` 可以读取定位芯片，但更改已创建广告的定位不支持 — 定位在创建时通过 `create_ad` 设置。
- **没有 CI 中的实时端到端测试。** 命中的实时 ads.telegram.org 测试标记为 `live`，需要真实会话，从不自动运行 — 需要具有活动账户的人类在本地运行它们。
- **传输仅限标准输入/输出。** 此版本中没有远程/HTTP 传输或 Docker 映像。
## 许可证
[MIT](LICENSE)
