AI导哈

Meta Ads MCP服务器

一个Python实现的MCP服务器，用于将Meta Marketing API数据暴露给兼容MCP的客户端。

  • by phwtsp
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 phwtsp/meta-ads-mcp-server

使用说明

元广告MCP服务器

Python MCP 服务器，用于向 MCP 兼容的客户端暴露 Meta Marketing API 数据。

什么已经改变

此服务器版本已调整为更可靠的运行 ：

  • 载入 .env 自动在项目根
  • 启动失败 META_ACCESS_TOKEN 未配置
  • 返回所有工具中的结构化JSON
  • 选择 date_preset, level e metric 在调用 Meta API 之前
  • 删除静默错误并将可执行错误返回到 MCP 客户端
  • 美国 streamable-http 当 PORT 它是明确的

要求

  • Python 3.10+
  • 具有兼容权限的Meta令牌，例如 ads_read e read_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检查限制和速率限制

相关 MCP