Newsbreak Ads MCP

NewsBreak广告MCP服务器

用于NewsBreak Business API的模型上下文协议（MCP）服务器，使用FastMCP构建。该服务器通过NewsBreak广告平台为分析、报告和活动管理提供工具和资源。

特性

MCP工具

服务器提供以下工具，用于与NewsBreak的广告API交互：

分析和报告（主要关注点）

• get_ad_accounts -检索指定组织ID的广告帐户
• get_campaigns -列出支持过滤和分页的活动
• get_tracking_events -访问像素和回发跟踪事件
• run_performance_report -使用自定义指标和维度生成同步性能报告
• get_campaign_summary -快速概述最近的活动表现

MCP资源

通过URI模板可用的只读资源：

• accounts://{org_id}/ad-accounts -组织的广告账户
• campaigns://{ad_account_id}/active -广告帐户的活动
• events://{ad_account_id}/tracking -跟踪广告帐户的事件

先决条件

• Python 3.10或更高版本
• 商业新闻
• NewsBreak API访问令牌

安装

1. 克隆或下载此存储库

1. 安装依赖项

pip install -r requirements.txt

1. 配置环境变量

创建一个 .env 项目根目录中的文件：

cp .env.example .env

编辑 .env 并添加您的NewsBreak访问令牌：

NEWSBREAK_ACCESS_TOKEN=your_access_token_here

获取您的访问令牌

1. 登录 商业新闻
2. 导航到您的帐户设置
3. 转到API部分
4. 生成或复制您的访问令牌

用法

服务器支持多种身份验证方法和传输选项。

命令行选项

python server.py --help

Options:
  --token TOKEN        NewsBreak API access token (overrides environment variable)
  --transport {stdio,http,sse}
                       Transport method (default: stdio)
  --host HOST         Host for HTTP/SSE transport (default: localhost)
  --port PORT         Port for HTTP/SSE transport (default: 8000)
  --version           Show version and exit

方案1：地方发展（STDIO）

方法1A：使用命令行参数（推荐）

python server.py --token YOUR_ACCESS_TOKEN

方法1B：使用环境变量

# Ensure .env file has NEWSBREAK_ACCESS_TOKEN set
python server.py

方法1C：使用run脚本

./run_server.sh

选项2:Claude桌面集成

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

方法2A：通过命令行参数传递令牌（推荐-更安全）

{
  "mcpServers": {
    "newsbreak-ads": {
      "command": "python",
      "args": [
        "/path/to/newsbreak-ads-mcp-server/server.py",
        "--token",
        "your_access_token_here"
      ]
    }
  }
}

方法2B：通过环境变量传递令牌

{
  "mcpServers": {
    "newsbreak-ads": {
      "command": "python",
      "args": [
        "/path/to/newsbreak-ads-mcp-server/server.py"
      ],
      "env": {
        "NEWSBREAK_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

方法2C：使用.env文件（最安全-配置中没有标记）

{
  "mcpServers": {
    "newsbreak-ads": {
      "command": "python",
      "args": [
        "/path/to/newsbreak-ads-mcp-server/server.py"
      ]
    }
  }
}

注：需要 .env 提交 NEWSBREAK_ACCESS_TOKEN 在项目目录中

更新配置后重新启动Claude Desktop。

选项3:HTTP服务器

作为HTTP服务器运行以进行远程访问：

# Using command-line token
python server.py --token YOUR_TOKEN --transport http --port 8000

# Or using environment variable
python server.py --transport http --port 8000 --host 0.0.0.0

# Or using fastmcp CLI
fastmcp run server.py --transport http --port 8000

服务器将在以下位置可用： http://localhost:8000/mcp

选项4:FastMCP云

部署到FastMCP Cloud以实现即时HTTPS端点：

# Make sure to set NEWSBREAK_ACCESS_TOKEN in cloud environment
fastmcp deploy --config fastmcp_cloud.json

示例用法

获取广告帐户

# In Claude or through MCP client
use_mcp_tool(
    server="newsbreak-ads",
    tool="get_ad_accounts",
    arguments={
        "org_ids": ["123456789"]
    }
)

运行性能报告

use_mcp_tool(
    server="newsbreak-ads",
    tool="run_performance_report",
    arguments={
        "ad_account_id": "987654321",
        "date_from": "2024-01-01",
        "date_to": "2024-01-31",
        "dimensions": ["date", "campaign_id"],
        "metrics": ["impressions", "clicks", "spend", "conversions"],
        "level": "campaign"
    }
)

获取活动摘要

use_mcp_tool(
    server="newsbreak-ads",
    tool="get_campaign_summary",
    arguments={
        "ad_account_id": "987654321",
        "days": 7
    }
)

访问资源

read_resource(
    uri="campaigns://987654321/active"
)

可用工具

get_ad_accounts(org_ids: List[str])

检索指定组织ID的所有广告帐户。

参数：

• org_ids：组织ID列表

退货： JSON与组织及其广告帐户

get_campaigns(ad_account_id: str, page_no: int = 1, page_size: int = 50, search: Optional[str] = None, online_status: Optional[str] = None)

列出具有可选过滤和分页功能的活动。

参数：

• ad_account_id：目标广告帐户ID
• page_no：页码（默认值：1）
• page_size：每页结果-选项：5、10、20、50、100、200、500（默认值：50）
• search：可选搜索查询
• online_status：按状态筛选（警告、未激活、活动、已删除）

退货： 带有活动和分页信息的JSON

get_tracking_events(ad_account_id: str, os_filter: Optional[str] = None)

检索广告帐户的跟踪事件（像素和回邮）。

参数：

• ad_account_id：目标广告帐户ID
• os_filter：可选操作系统过滤器（“IOS”、“ANDROID”或“web”）

退货： 带有跟踪事件的JSON

run_performance_report(ad_account_id: str, date_from: str, date_to: str, dimensions: Optional[List[str]] = None, metrics: Optional[List[str]] = None, level: Optional[str] = None)

生成同步性能报告。

参数：

• ad_account_id：目标广告帐户ID
• date_from：开始日期（YYYY-MM-DD）
• date_to：结束日期（YYYY-MM-DD）
• dimensions：可选维度（例如，\[“日期”、“活动id”\]）
• metrics：可选指标（例如，\[“印象”、“点击”、“支出”\]）
• level：报告级别（“活动”、“ad_set”、“ad”）

退货： JSON与报告数据

get_campaign_summary(ad_account_id: str, days: int = 7)

快速总结最近的活动表现。

参数：

• ad_account_id：目标广告帐户ID
• days：回顾的天数（默认值：7）

退货： 带有活动摘要的JSON

建筑

服务器由以下组件构建：

• server.py -带工具和资源的主FastMCP服务器
• client.py -NewsBreak API客户端包装，具有身份验证和速率限制
• models.py -用于类型安全和验证的Pydantic数据模型
• fastmcp.json -FastMCP部署配置
• .env -环境变量（未提交到git）

主要特点

• 速率限制：内置速率限制器（默认情况下为10个请求/秒）
• 错误处理：使用指数回退自动重试
• 类型安全：完整的Pydantic模型验证
• 异步/等待：高性能异步操作
• 基于环境的配置：安全的凭据管理

API 参考

此服务器实现以下NewsBreak Business API终结点：

• GET /v1/ad-account/getGroupsByOrgIds -获取广告帐户
• GET /v1/campaign/getList -列出活动
• GET /v1/event/getList/{adAccountId} -获取跟踪事件
• POST /v1/report/runSync -运行同步报告

基本URL: https://business.newsbreak.com/business-api/v1

认证：访问令牌标头

有关API完整文档，请访问：https://business.newsbreak.com/business-api-doc/docs/overview/

故障排除

“未设置NEWSBREAK_ACCESS_TOKEN环境变量”

确保您已创建 .env 使用您的访问令牌文件或在您的环境中设置它：

export NEWSBREAK_ACCESS_TOKEN=your_token_here

“NewsBreak API错误：令牌无效”

您的访问令牌可能已过期或无效。从您的NewsBreak for Business帐户生成一个新的。

速率限制

客户端包括内置的速率限制（10个要求/秒）。如果需要对此进行调整：

client = NewsBreakClient(access_token="...", rate_limit=5)  # 5 requests per second

连接超时

默认超时为30秒。必要时进行调整：

client = NewsBreakClient(access_token="...", timeout=60.0)  # 60 seconds

发展

项目结构

newsbreak-ads-mcp-server/
├── server.py                   # Main MCP server
├── client.py                   # API client wrapper
├── models.py                   # Pydantic models
├── requirements.txt            # Python dependencies
├── fastmcp.json               # STDIO deployment config
├── fastmcp_cloud.json         # Cloud deployment config
├── claude_desktop_config.json # Claude Desktop example
├── run_server.sh              # Local run script
├── .env.example               # Environment template
├── .env                       # Your credentials (gitignored)
├── .gitignore
└── README.md

运行测试

# Install dev dependencies
pip install pytest pytest-asyncio httpx

# Run tests (when implemented)
pytest

贡献

欢迎投稿！需要改进的领域：

• \[\]添加对异步报告的支持
• \[\]实现自定义报告创建
• \[\]添加广告集和广告管理工具
• \[\]创建全面的测试套件
• \[\]添加更多资源模板
• \[\]实现webhook支持
• \[\]为频繁访问的数据添加缓存层

许可证

MIT许可证-可根据需要自由使用和修改。

支持

对于以下问题：

• 此MCP服务器：在此存储库中打开一个问题
• 新闻快讯API：通过您的企业帐户联系NewsBreak支持
• FastMCP框架：参观https://github.com/jlowin/fastmcp

链接

• 商业新闻
• NewsBreak API文档
• FastMCP文档
• 模型上下文协议

______________________________________________________________________

内置 FastMCP v2.13.0