Mlg Meta MCP

mlg元mcp

   

Meta Ads的开源MCP服务器——30个工具，涵盖帐户发现、活动/广告集/广告管理、目标研究、创意检查、见解和LLM友好的工作流程。

mlg-meta-mcp 是为那些希望通过Meta Marketing API实现瘦代理的开发人员和运营商设计的。它增加了客户发现、面向业务的输出、生产力工具、比较流程和目标/创意工具，这些工具更容易让LLM和代理在实际工作流程中使用。

为什么这个项目存在

许多Meta Ads MCP服务器停止公开原始API调用。这很有用，但对于真正的代理工作流来说并不总是足够的。

该项目旨在使日常使用更加实用：

• 自动帐户发现 而不是硬连线一个账户
• 以业务为导向的见解 而不是原始的公制转储
• 更安全的生产操作 如克隆和批量状态更改
• LLM友好的回应 总结发生了什么以及为什么它很重要
• 结构化比较逻辑 用于逐期分析

合同设计原则

核心MCP工具应该为最广泛的消费者群体返回最大的有用信号。

• 消费者（LLM、应用程序、提示、UI层）自己的过滤和解释
• 格式和人体工程学总结都很好
• 基础工具契约中有用信号的破坏性滤波不是
• 特定于项目的业务规则应该存在于更高级别的工作流中，而不是中立的核心工具输出中

今天包括什么

帐户发现

• 发现配置的系统用户令牌可访问的所有广告帐户
• 按ID或帐户名解析帐户
• 获取完整的帐户信息（姓名、货币、时区、业务、状态）

活动操作

• 获取活动
• 获取完整的活动详情（投标策略、购买类型、特殊广告类别、问题）
• 创建活动
• 更新活动
• 暂停活动
• 激活活动

广告集操作

• 从帐户或活动中获取广告集
• 获取完整的广告集详细信息（目标、优化目标、出价金额、有效状态）
• 创建广告集
• 更新广告集
• 暂停广告集
• 激活广告集

广告运营

• 获取广告
• 获取完整的广告详细信息（有效状态、创意ID、问题）
• 更新广告（状态和出价金额）

创意检查

• 将创意附加到广告中（object_story_spec、图像哈希、行动呼吁）

目标研究

• 按关键字搜索兴趣
• 从种子列表中获取兴趣建议
• 按姓名或元ID验证兴趣
• 浏览行为
• 浏览人口统计类别
• 按关键字搜索地理位置

预算安排

• 为活动创建有时间限制的预算增长或乘数

见解和分析

• 获取帐户、活动、广告集或广告的见解
• 比较两个具有业务感知回退逻辑的显式时段

生产力工具

• 克隆广告系列（含广告集）
• 克隆广告集
• 批量暂停活动
• 批量激活活动
• 检查具有可配置阈值的警报

突出显示的工作流

此MCP对以下工作流程特别有用：

1. 自动发现可访问的广告帐户
2. 检查活动、广告集、广告或帐户性能
3. 比较两个时期的活动绩效
4. 快速复制获胜结构
5. 在一个操作中暂停或激活多个活动
6. 从Meta Ads数据生成面向警报的摘要
7. 研究和验证目标受众
8. 通过有效状态和问题信息诊断交付问题

如何 compareTwoPeriods 作品

compareTwoPeriods 比较四个级别之一的两个显式时段之间的性能：

• account
• campaign
• adset
• ad

双方现在接受以下任一条件：

• datePreset (today, yesterday, last_7d, last_30d, this_month, last_month)
• timeRange 和 { since, until } 在 YYYY-MM-DD 格式

该工具还支持显式结果选择：

• primary_from_insights （默认）--从洞察中解析一种操作类型，并将其应用于两个时段
• specific_action --比较一个显式Meta action_type 喜欢 lead 或 purchase
• all_actions --对所有动作类型求和

它还支持可选的度量选择：

• spend
• results
• cpr
• impressions
• clicks
• ctr

如果 metrics 如果省略，该工具将保留向后兼容的默认设置： spend, results，以及 cpr.

现在，响应使解析结果定义明确，以便消费者可以看到 results 意味着。

对于 account, adset，以及 ad

比较是直接的：

• 同一对象的当前期间
• 同一对象的上一时段

对于 campaign

活动比较使用更智能的回退链：

1. 上一时期的同一活动
2. 同一账户中最相似的活动
3. 上期账户活动平均值
4. 无可用参考

工具响应明确地告诉用户使用了哪个引用。

类似的竞选逻辑

类似的竞选回退不仅仅基于命名。

它要求：

• 同一场运动 objective
• 相同的主导广告集 optimizationGoal

然后，它使用以下方式对有效候选人进行排名：

• 预算相似性
• 投标策略匹配
• 计费事件匹配
• 名字相似性是决胜局

安装

git clone https://github.com/iammalego/mlg-meta-mcp.git
cd mlg-meta-mcp
npm install
cp .env.example .env

然后编辑 .env 使用您的Meta凭据。

配置

必需的环境变量

META_SYSTEM_USER_TOKEN=your_system_user_token_here
META_API_VERSION=v22.0
LOG_LEVEL=info

所需的元权限

您的令牌应具有适合您要运行的操作的权限。在大多数设置中，包括：

• ads_management
• ads_read
• business_management

本地开发

npm run dev

生产建设

npm run build
npm start

MCP客户端设置

克劳德桌面

将此添加到 claude_desktop_config.json:

{
  "mcpServers": {
    "mlg-meta-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/mlg-meta-mcp/dist/index.js"],
      "env": {
        "META_SYSTEM_USER_TOKEN": "your_token_here",
        "META_API_VERSION": "v22.0",
        "LOG_LEVEL": "info"
      }
    }
  }
}

通用stdio使用

任何支持stdio传输的MCP客户端都可以通过启动编译的 dist/index.js 入口点。

可用工具

总共30个工具。

账户工具

• discoverAdAccounts
• getAccountInfo

活动工具

• getCampaigns
• getCampaignDetails
• updateCampaign
• pauseCampaign
• activateCampaign
• cloneCampaign
• bulkPauseCampaigns
• bulkActivateCampaigns

广告设置工具

• getAdSets
• getAdSetDetails
• updateAdSet
• pauseAdSet
• activateAdSet
• cloneAdSet

广告工具

• getAds
• getAdDetails
• updateAd

创意工具

• getAdCreatives

目标定位工具

• searchInterests
• getInterestSuggestions
• validateInterests
• searchBehaviors
• searchDemographics
• searchGeoLocations

预算工具

• createBudgetSchedule

洞察工具

• getInsights
• compareTwoPeriods
• checkAlerts

示例提示

以下是此MCP旨在很好地支持的提示类型：

• “列出使用此令牌可访问的所有广告帐户。”
• “显示名为Plannit的帐户的活动。”
• “获取活动123的完整详细信息，包括问题和交付状态。”
• “比较last_7d和last_30d之间的此活动。”
• “如果前一时期不存在该活动，请解释使用了哪个回退参考。”
• “复制此活动并将其预算减少20%。”
• “先暂停这些竞选活动。”
• “使用5000的心肺复苏阈值检查昨天的警报。”
• “搜索与‘可持续时尚’相关的兴趣，并推荐相关兴趣。”
• “在将这些兴趣ID用于新广告集之前，请先验证它们。”
• “本周末为123号活动增加20%的预算。”

建筑

代码库被有意地分成几层：

• src/tools/index.ts → MCP工具定义和Zod优先模式
• src/tools/handlers.ts → 面向MCP的处理程序和MCP响应信封（文本摘要以及有用的结构化内容）
• src/services/* → 业务逻辑
• src/api/* → Meta API客户端(GraphClient, InsightsClient, BusinessClient, TargetingClient, CreativeClient)
• src/types/* → 共享类型

这种分离有助于保持MCP表面、业务逻辑和Meta API集成的独立性。

例如， getInsights 保持可读的文本摘要，但非账户级别也保留了逐项列出的结构化指标，以便客户可以进行自己的排名、过滤和解释。

compareTwoPeriods 遵循同样的想法：文本输出只包括请求的（或默认的）指标，而 structuredContent.metrics 公开请求的度量列表和返回的每个度量值/更改对象。

质量和项目状态

当前技术基础：

• TypeScript严格模式
• Zod第一个工具模式
• 使用Pino进行结构化日志记录
• 分类错误处理
• Vitest测试设置
• 通过stdio集成MCP SDK

项目状态：

• 积极发展
• 适合本地/自托管使用
• 专注于为MCP客户和代理提供实用的Meta Ads工作流程

路线图

计划功能：

• 分娩诊断 --解释为什么一个活动、广告集或广告没有交付（计费问题、违反政策、家长暂停、出价过低等） issues_info 和 effective_status
• 学习阶段状态 --暴露广告集是否正在学习，还有多少转换要退出，以及是否正在学习 LEARNING_LIMITED 为什么
• 广告疲劳检测 --通过结合频率趋势和点击率衰减来检测广告何时需要创意旋转
• 归因比较 --同一对象的1d/7d点击和查看归因窗口的并排视图
• 安置明细 --按位置排列的表演（Feed、Stories、Reels、观众网络、Messenger）

未来可能的发展方向：

• 远程MCP支持
• 更广泛的自动化和监控流程

测试

npm test
npm run test:coverage
npm run type-check
npm run lint

文档

• 建筑
• API 参考
• 贡献
• 更新日志

贡献

欢迎提供意见、问题和反馈。

如果你想做出贡献，从以下方面开始：

1. 阅读架构文档
2. 检查现有问题
3. 提出一个有针对性的公关或改进建议

许可证

MIT© iammalego

致谢

• 模型上下文协议
• 元营销API
• 开源MCP生态系统