元广告MCP服务器
Python MCP 服务器，用于向 MCP 兼容的客户端暴露 Meta Marketing API 数据。
什么已经改变
此服务器版本已调整为更可靠的运行 ：
- 载入
.env自动在项目根 - 启动失败
META_ACCESS_TOKEN未配置 - 返回所有工具中的结构化JSON
- 选择
date_preset,levelemetric在调用 Meta API 之前 - 删除静默错误并将可执行错误返回到 MCP 客户端
- 美国
streamable-http当PORT它是明确的
要求
- Python 3.10+
- 具有兼容权限的Meta令牌，例如
ads_readeread_insights
安装
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt配置
创建文件 .env 雷兹：
META_ACCESS_TOKEN=EAAB...可选的， 创建 clients.json 对于账户昵称：
{
"Minha Marca": "act_123456789",
"Cliente Agencia X": "act_987654321"
}也可以使用 CLIENTS_JSON 作为具有相同JSON内容的环境变量。
执行
公共主机（Public Hosting）
如果您公开托管此服务器（例如在渲染中），强烈建议设置环境变量 MCP_API_KEY.
- 在服务器（ 渲染） ： 添加变量
MCP_API_KEY有你喜欢的秘密价值。 - 没有客户（前：克劳德桌面）： 在远程服务器配置中添加授权头。
Modo HTTP用于部署（渲染）
当......的时候 PORT 如果设置，则服务器使用SSE（服务器发送事件）。
PORT=8000 MCP_API_KEY=seu_segredo_aqui python3 server.py当......的时候 PORT 设置，服务器使用 streamable-http这是最符合当前MCP生产SDK的途径。
MCP 配置示例
{
"mcpServers": {
"meta-ads": {
"command": "/ABSOLUTE/PATH/.venv/bin/python",
"args": ["/ABSOLUTE/PATH/server.py"],
"env": {
"META_ACCESS_TOKEN": "EAAB..."
}
}
}
}可用工具
| 工具 | 功能 |
|---|---|
meta_list_clients 列出已配置的客户端 | |
meta_get_structure 列出广告系列或详细说明广告系列的 adsets/ads | |
meta_get_analytics | 返回帐户、广告系列、adset 或广告的结构化见解 |
meta_get_ad_creative_details | 返回广告创作者的数据 |
meta_get_account_balance 返回账户余额，支出和支出上限。 | |
meta_get_demographics 按年龄/性别和平台分类。 | |
meta_compare_performance | 比较多个IDS |
meta_get_trend_chart 返回ASCII时间序列和图形。 |
答案格式
所有工具都会以此信封返回 JSON：
{
"ok": true,
"data": {}
}如果发生错误：
{
"ok": false,
"error": {
"code": "invalid_params",
"message": "date_preset inválido.",
"details": {}
}
}常见问题
META_ACCESS_TOKEN não definido
- 设置环境变量或文件
.env
ModuleNotFoundError: No module named 'mcp'
- 启用正确的虚拟环境
- 骑
pip install -r requirements.txt
account_ambiguous
- 使用客户的确切名称
clients.json哦act_ID
meta_api_error
- 有效的令牌权限
- 确认所提供的ID是否属于正确的帐户/令牌
- 从Meta API检查限制和速率限制