1. 项目概述一个让AI助手直接操作Meta广告的本地桥梁如果你和我一样日常需要和MetaFacebook/Instagram广告平台打交道同时又重度依赖像Claude Code、Cursor这类AI编程助手来提升效率那你肯定想过能不能让AI直接帮我查广告数据、调预算、甚至创建新的广告系列今天要聊的这个开源项目armavita-meta-ads-mcp就是为解决这个问题而生的。它本质上是一个本地运行的MCP服务器专门为Meta Ads的Marketing API做了封装。简单来说MCPModel Context Protocol是Anthropic推出的一套协议它允许像Claude这样的AI模型通过一个标准的“服务器”去访问外部工具和数据。你可以把它想象成AI的“USB接口”标准。而这个项目就是一个专门为Meta广告API定制的“USB设备”。把它运行在你的电脑上配置到你的AI助手Claude Code、Cursor、Codex等里你的AI助手就瞬间获得了直接查询、分析甚至操作你Meta广告账户的能力。这不再是简单的聊天和代码生成而是让AI成为了一个能直接调用专业API的“数字员工”。对于广告优化师、增长工程师、独立开发者或中小团队的营销负责人来说这个工具的价值在于将重复、繁琐的广告平台操作自动化、智能化。比如你可以让AI帮你“查一下上周所有广告系列的ROAS把低于2的系列预算调低50%”或者“根据这个产品描述生成5个不同的广告文案和兴趣定位建议”。这一切都可以在你熟悉的代码编辑器或AI对话界面中用自然语言完成。2. 核心原理与架构拆解MCP协议如何赋能AI操作广告要理解这个项目为什么有用得先弄明白MCP协议和传统API调用的区别。我们平时写脚本调用Meta API需要自己处理OAuth认证、构造HTTP请求、解析JSON响应、处理分页和错误。虽然有很多SDK简化了这些步骤但它仍然是一个“离线”的过程你需要先想好要做什么然后写代码最后运行。MCP引入了一个“在线”的、动态的交互层。这个armavita-meta-ads-mcp项目扮演的角色是一个协议转换器和安全代理。2.1 MCP服务器的工作机制当你在AI客户端如Claude Code中配置好这个MCP服务器后其工作流程是这样的AI发起请求你在AI的聊天框里输入“列出我所有广告账户下过去7天的花费。”客户端路由AI客户端识别出你的意图涉及“Meta广告数据”于是它不会自己去瞎猜而是将这条指令按照MCP协议封装成一个结构化的请求通过stdio标准输入输出发送给你本地正在运行的armavita-meta-ads-mcp服务器进程。服务器处理MCP服务器收到请求解析出需要调用哪个“工具”Tool。比如这个请求对应的是list_insights工具。服务器会从请求参数中提取出date_range例如last_7d、需要的字段如spend,impressions以及相关的广告账户ID。调用真实API服务器使用你预先配置好的访问令牌Access Token向Meta的Marketing API默认v25.0版本发起一个真正的HTTP请求。数据转换与返回服务器收到Meta API返回的原始JSON数据后会进行一些处理比如确保分页信息完整过滤或脱敏敏感信息如令牌在URL中被自动隐藏然后将数据重新封装成MCP协议规定的格式。AI接收与呈现处理后的数据通过stdio传回AI客户端。AI模型接收到这些结构化的数据后就能够理解并组织语言以清晰、可读的方式回答你的问题比如“过去7天你的三个广告账户总花费为$1234。其中账户A花费$800ROAS为3.2账户B花费$300...”这个架构的关键优势在于解耦。AI模型不需要知道Meta API的具体细节、认证方式或数据格式它只需要懂得标准的MCP协议。而MCP服务器则封装了所有领域特定的复杂逻辑。这种设计使得AI的能力可以通过增删MCP服务器来灵活扩展。2.2 项目架构的核心设计要点浏览项目代码虽然正文未提供但通过文档可推断其设计有以下几个值得称道的地方双模式认证同时支持直接使用长期有效的META_ACCESS_TOKEN和更安全的本地OAuth流程META_APP_IDMETA_APP_SECRET。后者尤其适合团队协作或对安全性要求高的场景因为配置文件中不存储实际的令牌令牌通过一次性的登录流程获得并可能存储在系统密钥链中。工具覆盖全面从项目列出的Tool Coverage来看它几乎覆盖了广告运营的完整生命周期账户管理、广告系列/组/广告的CRUD、预算排期、创意素材上传、数据洞察、受众定位、甚至竞品广告库Ads Library搜索和内容研究。这意味着AI能帮你做的事情非常多。原生分页支持正确处理了Meta API的游标分页Cursor-based Pagination。这对于处理大量数据如列出所有历史广告至关重要。服务器会将分页信息原样返回AI客户端可以决定是否以及如何请求下一页数据。数据洞察标准化对insights查询做了很好的封装支持灵活的日期范围具体日期或预设周期如last_30d和对比周期。这简化了生成常见报告如“对比上月同期”的复杂度。注意这是一个“本地”服务器意味着所有数据流量都发生在你的机器和Meta服务器之间不会经过第三方中转这在数据安全和隐私上是很大的优势。但同时它也需要你在自己的环境里安装、配置和运行。3. 从零开始详细安装与配置指南理论讲完了我们来点实际的。下面是一份从零开始在macOS/Linux系统上配置并使用这个MCP服务器的完整指南。Windows用户使用WSL或PowerShell也可参照类似步骤。3.1 环境准备与依赖安装首先确保你的系统有Python 3.11或更高版本。推荐使用uv或pip进行包管理uv是新一代的高速Python包安装器体验更好。# 1. 克隆项目仓库假设你想从源码安装或查看 git clone https://github.com/EfrainTorres/armavita-meta-ads-mcp.git cd armavita-meta-ads-mcp # 2. 使用uv同步依赖项目推荐方式 # 如果你没有uv先安装curl -LsSf https://astral.sh/uv/install.sh | sh uv sync # 或者使用传统的pip确保在虚拟环境中 python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows pip install mcp[cli]1.26.0 # 其他依赖会根据项目pyproject.toml自动安装如果项目已发布到PyPI你也可以直接安装pip install armavita-meta-ads-mcp3.2 获取Meta API凭证这是最关键也最麻烦的一步。你需要一个Meta开发者账号和应用。访问Meta开发者平台前往 developers.facebook.com 创建一个应用。应用类型选择“业务”。添加营销API产品在应用面板中找到“添加产品”选择“Marketing API”。配置权限你的应用需要获取相应的权限Scopes。对于这个MCP服务器至少需要以下权限ads_management管理广告ads_read读取广告数据business_management管理商业账户如果你需要使用Pages相关功能可能还需要pages_read_engagement。获取应用ID和密钥在“设置”-“基本”里找到“应用编号”META_APP_ID和“应用密钥”META_APP_SECRET。务必保管好密钥不要泄露。获取访问令牌Access Token方式一快速测试在“工具”-“Graph API资源管理器”中选择你的应用点击“生成访问令牌”选择你需要的权限会生成一个短期通常1-2小时的用户访问令牌。这个令牌可以直接用作META_ACCESS_TOKEN。方式二长期使用你需要完成“应用审核”流程获取长期有效的“系统用户”访问令牌或者配置OAuth让用户你自己授权。对于个人或小团队使用走“系统用户”路线相对简单。在“系统用户”标签页创建一个系统用户为其分配资产广告账户然后为该用户生成一个长期令牌。3.3 配置AI客户端以Claude Code为例不同的AI客户端配置MCP服务器的方式略有不同但核心都是修改一个JSON配置文件。这里以Claude Code或Cursor内置的Claude为例它通常使用claude_desktop_config.json文件。找到配置文件位置macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件不存在就创建一个。编辑配置文件你需要根据选择的认证模式添加MCP服务器配置。模式A使用直接访问令牌简单适合个人快速启动{ mcpServers: { meta-ads: { command: armavita-meta-ads-mcp, env: { META_ACCESS_TOKEN: EAALwBZC...你的长令牌, META_GRAPH_API_VERSION: v25.0 } } } }重要提示将令牌直接写在配置文件里存在安全风险。确保该配置文件只有你可读并且不要将此配置文件提交到公开的版本控制系统如GitHub。模式B使用OAuth流程更安全推荐{ mcpServers: { meta-ads: { command: armavita-meta-ads-mcp, env: { META_APP_ID: 123456789012345, META_APP_SECRET: abc123def456ghi789jkl012mno345pqr } } } }在这种模式下你需要在终端运行一次登录命令来获取令牌armavita-meta-ads-mcp --login这会打开浏览器引导你完成Meta的OAuth授权流程。成功后令牌会被安全地存储在你的系统密钥链中而不是明文的配置文件里。重启AI客户端保存配置文件后完全退出并重新启动Claude Code或Cursor以使配置生效。4. 实战演练用AI助手完成典型广告运营任务配置成功后你的AI助手就“觉醒”了。下面通过几个具体场景展示如何与AI协作。4.1 场景一快速诊断账户健康状况你刚休假回来想快速了解过去一个月广告账户的整体表现。你对AI说“帮我分析一下主广告账户ID: act_123456789过去30天的核心表现指标按广告系列分组并找出花费最高和ROAS最低的系列。”AI背后的操作AI识别意图调用MCP服务器的list_insights工具。请求参数大致为account_idact_123456789,date_rangelast_30d,levelcampaign,fieldsspend,impressions,clicks,conversions,reach,campaign_name。服务器获取数据后返回给AI。AI分析数据可能会这样回复你 “过去30天你的账户总花费$15200获得2.1万次点击转化率为4.1%。共运行了8个广告系列。花费最高‘夏季大促主推’系列花费$6500ROAS为2.8。ROAS最低‘品牌测试-新受众’系列花费$800ROAS仅为0.9建议检查其受众定位或创意。 详细数据如下表...” AI甚至可以主动建议“是否需要我帮你把ROAS低于1.5的系列预算暂停”4.2 场景二克隆并优化一个成功的广告活动你发现一个名为“黑五折扣-A”的广告组ad set表现很好想复制它的结构但更换素材和调整部分定位用于“黑五折扣-B”产品。你对AI说“克隆广告组 ‘黑五折扣-A’ (ID: 987654321)新的广告组命名为‘黑五折扣-B’。在新广告组里把兴趣定位从‘户外运动’改为‘健身瑜伽’并上传这张新图片附上图片路径作为主图。”AI背后的操作AI首先调用clone_ad_set工具传入源广告组ID和目标名称。克隆成功后获得新广告组ID。接着调用update_ad_set工具修改其targeting字段中的兴趣信息。然后调用upload_ad_image_asset工具将你指定的本地图片上传到Meta获得一个图片哈希hash。最后AI可能会调用create_ad_creative和create_ad或者直接update_ad将新图片应用到新广告组下的广告中。AI回复“已完成。已成功克隆广告组新ID为 123456789。兴趣定位已更新为‘健身瑜伽’。图片‘product_b.jpg’已上传哈希a1b2c3d4并应用于新广告。新广告系列已处于草稿状态请检查后激活。”4.3 场景三进行受众调研和竞品分析你计划推出一款新的咖啡机想研究目标受众和竞品广告。你对AI说“搜索与‘家用意式咖啡机’、‘精品咖啡’相关的兴趣关键词并估算一下在美国25-45岁女性中的潜在受众规模。另外去Ads Library里搜一下最近三个月主要咖啡机品牌比如Breville, De‘Longhi的广告看看他们在推什么卖点。”AI背后的操作对于受众调研AI调用search_interests和suggest_interests工具查找相关兴趣然后调用estimate_audience_size工具结合地理位置US、年龄、性别等参数进行估算。对于竞品分析AI调用search_ads_archive工具传入搜索关键词、广告主名称可能从search_pages获得、地区和时间范围。AI将两部分信息整合后回复你 “受众分析核心兴趣点包括‘拿铁艺术’、‘咖啡豆烘焙’、‘厨房电器’等。结合25-45岁女性定位美国潜在受众规模约在1200万-1500万。竞品广告分析最近三个月Breville主要强调‘一键式操作’和‘奶泡质量’De‘Longhi则突出‘复古设计’和‘耐用性’。常见视觉元素是咖啡拉花特写和厨房场景。建议你的广告可以从‘快速预热’或‘易于清洁’的差异化角度切入。” 它甚至能附上几条竞品广告的文案示例。5. 高级技巧与避坑指南在实际使用中我总结了一些能极大提升体验和避免问题的技巧。5.1 认证与令牌管理的最佳实践优先使用OAuth模式尽管配置稍复杂但OAuth模式避免了令牌硬编码且支持令牌刷新如果实现的话长期来看更安全、更省心。运行--login后令牌通常存储在系统钥匙串后续无需再操作。令牌权限与过期直接使用的META_ACCESS_TOKEN如果是用户令牌有效期很短约2小时。系统用户令牌有效期长约60天但也会过期。最稳妥的办法是定期检查令牌有效性或在AI操作失败时首先怀疑令牌过期。可以在MCP服务器配置中增加一个META_TOKEN_EXPIRY_CHECK的提示性环境变量提醒自己。分环境配置如果你有开发、测试、生产多个Meta应用可以在MCP配置中使用不同的“command”别名或脚本通过环境变量切换META_APP_ID和META_APP_SECRET。例如写一个shell脚本run_meta_mcp_dev.sh来设置环境变量并启动服务器。5.2 高效利用AI提示词Prompt要让AI更准确地调用MCP工具你的指令需要一定的“结构”。虽然不是严格必须但清晰的指令能减少AI的误解。提供明确ID在涉及具体资产账户、系列、组、广告时尽量提供准确的ID。例如“查看账户 act_123456789 的洞察”比“查看我的账户洞察”更精确尤其当你管理多个账户时。指定日期范围和层级查询数据时养成说明date_range和level的习惯。例如“获取过去7天在广告组层级的花费和转化数据。”分步复杂操作对于创建广告这种多步骤任务可以拆解。先让AI“为新产品X创建一个目标为转化的广告系列草稿日预算$50”检查无误后再指令它“在刚才创建的系列下创建一个针对兴趣A和B的广告组”最后“上传图片Y并创建广告”。这样每一步都可以确认。5.3 数据洞察查询的常见“坑”日期预设与对比list_insights支持last_30d,this_month,last_3d等预设值非常方便。但注意maximum会拉取该对象有数据以来的所有记录数据量可能巨大。使用create_report进行周期对比时确保comparison_period的日期范围长度与date_range一致否则对比可能不准确。字段选择与性能不要总是查询所有字段fieldsall。只请求你需要的字段如fieldsspend,impressions,clicks,cpc。这能显著提升API响应速度和减少数据处理负担。Meta API有些字段是默认不返回的如actions需要显式指定。分页处理当AI返回的数据说“以下是前25条结果”时意味着还有更多。你可以直接告诉AI“请获取下一页结果”或“获取全部结果”。AI会利用返回的paging.cursors.after值继续调用API。对于非常大的数据集可以考虑让AI先汇总关键指标而不是拉取所有明细行。5.4 错误排查与调试查看客户端日志Claude Code或Cursor通常有开发者控制台或日志文件。当AI操作失败时首先查看这里的错误信息。常见的错误包括“Invalid OAuth access token”令牌失效、“Permissions error”权限不足、“Invalid parameter”参数错误。独立测试MCP服务器你可以在终端直接运行armavita-meta-ads-mcp然后根据MCP协议手动输入一些简单的JSON请求来测试服务器是否正常响应。这有助于隔离问题是出在服务器配置还是AI客户端。权限是万恶之源95%的“API调用失败”问题都与权限有关。请反复确认你的应用已添加了所需的产品Marketing API系统用户或访问令牌已授予了必要的权限ads_management,ads_read等并且该令牌有权访问你指定的广告账户资产层级授权。6. 安全须知与项目边界最后必须强调一下安全和项目适用范围这直接关系到你的账户安全和数据隐私。本地运行数据不出境这是本项目最大的安全优势。你的Meta访问令牌和所有广告数据只在你的电脑和Meta服务器之间传输不经过ArmaVita或任何第三方服务器。服务器代码是开源的你可以审查。令牌保护无论是环境变量还是配置文件都要像保护密码一样保护你的META_ACCESS_TOKEN、META_APP_SECRET。切勿提交到公开仓库。考虑使用.env文件通过python-dotenv加载并加入.gitignore。最小权限原则在Meta开发者平台为你的应用或系统用户授予权限时只授予它完成必要功能所需的最小权限。例如如果只是读数据就不要给ads_management权限。项目边界清晰这是一个本地MCP服务器仅支持stdio传输模式。它不是一个SaaS服务没有Web界面也不提供远程访问。它的功能完全围绕Meta Marketing API封装不处理其他平台如Google Ads, TikTok Ads的API。这意味着它的能力深度和Meta API保持一致但广度仅限于此。使用这个工具就像是给你的AI助手配备了一套专业的Meta广告操作面板。它不能替代你的策略思考和创意判断但能极大地解放你在数据获取、重复操作和初步分析上的生产力。刚开始配置可能会遇到一些门槛但一旦跑通你会发现这种“用自然语言指挥AI操作专业系统”的工作流其流畅感和效率提升是革命性的。我个人最喜欢用它来做每日数据快览和A/B测试的初步设置把节省下来的时间用在更重要的广告策略优化和创意构思上。
基于MCP协议构建AI助手操作Meta广告的本地自动化工具
1. 项目概述一个让AI助手直接操作Meta广告的本地桥梁如果你和我一样日常需要和MetaFacebook/Instagram广告平台打交道同时又重度依赖像Claude Code、Cursor这类AI编程助手来提升效率那你肯定想过能不能让AI直接帮我查广告数据、调预算、甚至创建新的广告系列今天要聊的这个开源项目armavita-meta-ads-mcp就是为解决这个问题而生的。它本质上是一个本地运行的MCP服务器专门为Meta Ads的Marketing API做了封装。简单来说MCPModel Context Protocol是Anthropic推出的一套协议它允许像Claude这样的AI模型通过一个标准的“服务器”去访问外部工具和数据。你可以把它想象成AI的“USB接口”标准。而这个项目就是一个专门为Meta广告API定制的“USB设备”。把它运行在你的电脑上配置到你的AI助手Claude Code、Cursor、Codex等里你的AI助手就瞬间获得了直接查询、分析甚至操作你Meta广告账户的能力。这不再是简单的聊天和代码生成而是让AI成为了一个能直接调用专业API的“数字员工”。对于广告优化师、增长工程师、独立开发者或中小团队的营销负责人来说这个工具的价值在于将重复、繁琐的广告平台操作自动化、智能化。比如你可以让AI帮你“查一下上周所有广告系列的ROAS把低于2的系列预算调低50%”或者“根据这个产品描述生成5个不同的广告文案和兴趣定位建议”。这一切都可以在你熟悉的代码编辑器或AI对话界面中用自然语言完成。2. 核心原理与架构拆解MCP协议如何赋能AI操作广告要理解这个项目为什么有用得先弄明白MCP协议和传统API调用的区别。我们平时写脚本调用Meta API需要自己处理OAuth认证、构造HTTP请求、解析JSON响应、处理分页和错误。虽然有很多SDK简化了这些步骤但它仍然是一个“离线”的过程你需要先想好要做什么然后写代码最后运行。MCP引入了一个“在线”的、动态的交互层。这个armavita-meta-ads-mcp项目扮演的角色是一个协议转换器和安全代理。2.1 MCP服务器的工作机制当你在AI客户端如Claude Code中配置好这个MCP服务器后其工作流程是这样的AI发起请求你在AI的聊天框里输入“列出我所有广告账户下过去7天的花费。”客户端路由AI客户端识别出你的意图涉及“Meta广告数据”于是它不会自己去瞎猜而是将这条指令按照MCP协议封装成一个结构化的请求通过stdio标准输入输出发送给你本地正在运行的armavita-meta-ads-mcp服务器进程。服务器处理MCP服务器收到请求解析出需要调用哪个“工具”Tool。比如这个请求对应的是list_insights工具。服务器会从请求参数中提取出date_range例如last_7d、需要的字段如spend,impressions以及相关的广告账户ID。调用真实API服务器使用你预先配置好的访问令牌Access Token向Meta的Marketing API默认v25.0版本发起一个真正的HTTP请求。数据转换与返回服务器收到Meta API返回的原始JSON数据后会进行一些处理比如确保分页信息完整过滤或脱敏敏感信息如令牌在URL中被自动隐藏然后将数据重新封装成MCP协议规定的格式。AI接收与呈现处理后的数据通过stdio传回AI客户端。AI模型接收到这些结构化的数据后就能够理解并组织语言以清晰、可读的方式回答你的问题比如“过去7天你的三个广告账户总花费为$1234。其中账户A花费$800ROAS为3.2账户B花费$300...”这个架构的关键优势在于解耦。AI模型不需要知道Meta API的具体细节、认证方式或数据格式它只需要懂得标准的MCP协议。而MCP服务器则封装了所有领域特定的复杂逻辑。这种设计使得AI的能力可以通过增删MCP服务器来灵活扩展。2.2 项目架构的核心设计要点浏览项目代码虽然正文未提供但通过文档可推断其设计有以下几个值得称道的地方双模式认证同时支持直接使用长期有效的META_ACCESS_TOKEN和更安全的本地OAuth流程META_APP_IDMETA_APP_SECRET。后者尤其适合团队协作或对安全性要求高的场景因为配置文件中不存储实际的令牌令牌通过一次性的登录流程获得并可能存储在系统密钥链中。工具覆盖全面从项目列出的Tool Coverage来看它几乎覆盖了广告运营的完整生命周期账户管理、广告系列/组/广告的CRUD、预算排期、创意素材上传、数据洞察、受众定位、甚至竞品广告库Ads Library搜索和内容研究。这意味着AI能帮你做的事情非常多。原生分页支持正确处理了Meta API的游标分页Cursor-based Pagination。这对于处理大量数据如列出所有历史广告至关重要。服务器会将分页信息原样返回AI客户端可以决定是否以及如何请求下一页数据。数据洞察标准化对insights查询做了很好的封装支持灵活的日期范围具体日期或预设周期如last_30d和对比周期。这简化了生成常见报告如“对比上月同期”的复杂度。注意这是一个“本地”服务器意味着所有数据流量都发生在你的机器和Meta服务器之间不会经过第三方中转这在数据安全和隐私上是很大的优势。但同时它也需要你在自己的环境里安装、配置和运行。3. 从零开始详细安装与配置指南理论讲完了我们来点实际的。下面是一份从零开始在macOS/Linux系统上配置并使用这个MCP服务器的完整指南。Windows用户使用WSL或PowerShell也可参照类似步骤。3.1 环境准备与依赖安装首先确保你的系统有Python 3.11或更高版本。推荐使用uv或pip进行包管理uv是新一代的高速Python包安装器体验更好。# 1. 克隆项目仓库假设你想从源码安装或查看 git clone https://github.com/EfrainTorres/armavita-meta-ads-mcp.git cd armavita-meta-ads-mcp # 2. 使用uv同步依赖项目推荐方式 # 如果你没有uv先安装curl -LsSf https://astral.sh/uv/install.sh | sh uv sync # 或者使用传统的pip确保在虚拟环境中 python -m venv .venv source .venv/bin/activate # Linux/macOS # .venv\Scripts\activate # Windows pip install mcp[cli]1.26.0 # 其他依赖会根据项目pyproject.toml自动安装如果项目已发布到PyPI你也可以直接安装pip install armavita-meta-ads-mcp3.2 获取Meta API凭证这是最关键也最麻烦的一步。你需要一个Meta开发者账号和应用。访问Meta开发者平台前往 developers.facebook.com 创建一个应用。应用类型选择“业务”。添加营销API产品在应用面板中找到“添加产品”选择“Marketing API”。配置权限你的应用需要获取相应的权限Scopes。对于这个MCP服务器至少需要以下权限ads_management管理广告ads_read读取广告数据business_management管理商业账户如果你需要使用Pages相关功能可能还需要pages_read_engagement。获取应用ID和密钥在“设置”-“基本”里找到“应用编号”META_APP_ID和“应用密钥”META_APP_SECRET。务必保管好密钥不要泄露。获取访问令牌Access Token方式一快速测试在“工具”-“Graph API资源管理器”中选择你的应用点击“生成访问令牌”选择你需要的权限会生成一个短期通常1-2小时的用户访问令牌。这个令牌可以直接用作META_ACCESS_TOKEN。方式二长期使用你需要完成“应用审核”流程获取长期有效的“系统用户”访问令牌或者配置OAuth让用户你自己授权。对于个人或小团队使用走“系统用户”路线相对简单。在“系统用户”标签页创建一个系统用户为其分配资产广告账户然后为该用户生成一个长期令牌。3.3 配置AI客户端以Claude Code为例不同的AI客户端配置MCP服务器的方式略有不同但核心都是修改一个JSON配置文件。这里以Claude Code或Cursor内置的Claude为例它通常使用claude_desktop_config.json文件。找到配置文件位置macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json如果文件不存在就创建一个。编辑配置文件你需要根据选择的认证模式添加MCP服务器配置。模式A使用直接访问令牌简单适合个人快速启动{ mcpServers: { meta-ads: { command: armavita-meta-ads-mcp, env: { META_ACCESS_TOKEN: EAALwBZC...你的长令牌, META_GRAPH_API_VERSION: v25.0 } } } }重要提示将令牌直接写在配置文件里存在安全风险。确保该配置文件只有你可读并且不要将此配置文件提交到公开的版本控制系统如GitHub。模式B使用OAuth流程更安全推荐{ mcpServers: { meta-ads: { command: armavita-meta-ads-mcp, env: { META_APP_ID: 123456789012345, META_APP_SECRET: abc123def456ghi789jkl012mno345pqr } } } }在这种模式下你需要在终端运行一次登录命令来获取令牌armavita-meta-ads-mcp --login这会打开浏览器引导你完成Meta的OAuth授权流程。成功后令牌会被安全地存储在你的系统密钥链中而不是明文的配置文件里。重启AI客户端保存配置文件后完全退出并重新启动Claude Code或Cursor以使配置生效。4. 实战演练用AI助手完成典型广告运营任务配置成功后你的AI助手就“觉醒”了。下面通过几个具体场景展示如何与AI协作。4.1 场景一快速诊断账户健康状况你刚休假回来想快速了解过去一个月广告账户的整体表现。你对AI说“帮我分析一下主广告账户ID: act_123456789过去30天的核心表现指标按广告系列分组并找出花费最高和ROAS最低的系列。”AI背后的操作AI识别意图调用MCP服务器的list_insights工具。请求参数大致为account_idact_123456789,date_rangelast_30d,levelcampaign,fieldsspend,impressions,clicks,conversions,reach,campaign_name。服务器获取数据后返回给AI。AI分析数据可能会这样回复你 “过去30天你的账户总花费$15200获得2.1万次点击转化率为4.1%。共运行了8个广告系列。花费最高‘夏季大促主推’系列花费$6500ROAS为2.8。ROAS最低‘品牌测试-新受众’系列花费$800ROAS仅为0.9建议检查其受众定位或创意。 详细数据如下表...” AI甚至可以主动建议“是否需要我帮你把ROAS低于1.5的系列预算暂停”4.2 场景二克隆并优化一个成功的广告活动你发现一个名为“黑五折扣-A”的广告组ad set表现很好想复制它的结构但更换素材和调整部分定位用于“黑五折扣-B”产品。你对AI说“克隆广告组 ‘黑五折扣-A’ (ID: 987654321)新的广告组命名为‘黑五折扣-B’。在新广告组里把兴趣定位从‘户外运动’改为‘健身瑜伽’并上传这张新图片附上图片路径作为主图。”AI背后的操作AI首先调用clone_ad_set工具传入源广告组ID和目标名称。克隆成功后获得新广告组ID。接着调用update_ad_set工具修改其targeting字段中的兴趣信息。然后调用upload_ad_image_asset工具将你指定的本地图片上传到Meta获得一个图片哈希hash。最后AI可能会调用create_ad_creative和create_ad或者直接update_ad将新图片应用到新广告组下的广告中。AI回复“已完成。已成功克隆广告组新ID为 123456789。兴趣定位已更新为‘健身瑜伽’。图片‘product_b.jpg’已上传哈希a1b2c3d4并应用于新广告。新广告系列已处于草稿状态请检查后激活。”4.3 场景三进行受众调研和竞品分析你计划推出一款新的咖啡机想研究目标受众和竞品广告。你对AI说“搜索与‘家用意式咖啡机’、‘精品咖啡’相关的兴趣关键词并估算一下在美国25-45岁女性中的潜在受众规模。另外去Ads Library里搜一下最近三个月主要咖啡机品牌比如Breville, De‘Longhi的广告看看他们在推什么卖点。”AI背后的操作对于受众调研AI调用search_interests和suggest_interests工具查找相关兴趣然后调用estimate_audience_size工具结合地理位置US、年龄、性别等参数进行估算。对于竞品分析AI调用search_ads_archive工具传入搜索关键词、广告主名称可能从search_pages获得、地区和时间范围。AI将两部分信息整合后回复你 “受众分析核心兴趣点包括‘拿铁艺术’、‘咖啡豆烘焙’、‘厨房电器’等。结合25-45岁女性定位美国潜在受众规模约在1200万-1500万。竞品广告分析最近三个月Breville主要强调‘一键式操作’和‘奶泡质量’De‘Longhi则突出‘复古设计’和‘耐用性’。常见视觉元素是咖啡拉花特写和厨房场景。建议你的广告可以从‘快速预热’或‘易于清洁’的差异化角度切入。” 它甚至能附上几条竞品广告的文案示例。5. 高级技巧与避坑指南在实际使用中我总结了一些能极大提升体验和避免问题的技巧。5.1 认证与令牌管理的最佳实践优先使用OAuth模式尽管配置稍复杂但OAuth模式避免了令牌硬编码且支持令牌刷新如果实现的话长期来看更安全、更省心。运行--login后令牌通常存储在系统钥匙串后续无需再操作。令牌权限与过期直接使用的META_ACCESS_TOKEN如果是用户令牌有效期很短约2小时。系统用户令牌有效期长约60天但也会过期。最稳妥的办法是定期检查令牌有效性或在AI操作失败时首先怀疑令牌过期。可以在MCP服务器配置中增加一个META_TOKEN_EXPIRY_CHECK的提示性环境变量提醒自己。分环境配置如果你有开发、测试、生产多个Meta应用可以在MCP配置中使用不同的“command”别名或脚本通过环境变量切换META_APP_ID和META_APP_SECRET。例如写一个shell脚本run_meta_mcp_dev.sh来设置环境变量并启动服务器。5.2 高效利用AI提示词Prompt要让AI更准确地调用MCP工具你的指令需要一定的“结构”。虽然不是严格必须但清晰的指令能减少AI的误解。提供明确ID在涉及具体资产账户、系列、组、广告时尽量提供准确的ID。例如“查看账户 act_123456789 的洞察”比“查看我的账户洞察”更精确尤其当你管理多个账户时。指定日期范围和层级查询数据时养成说明date_range和level的习惯。例如“获取过去7天在广告组层级的花费和转化数据。”分步复杂操作对于创建广告这种多步骤任务可以拆解。先让AI“为新产品X创建一个目标为转化的广告系列草稿日预算$50”检查无误后再指令它“在刚才创建的系列下创建一个针对兴趣A和B的广告组”最后“上传图片Y并创建广告”。这样每一步都可以确认。5.3 数据洞察查询的常见“坑”日期预设与对比list_insights支持last_30d,this_month,last_3d等预设值非常方便。但注意maximum会拉取该对象有数据以来的所有记录数据量可能巨大。使用create_report进行周期对比时确保comparison_period的日期范围长度与date_range一致否则对比可能不准确。字段选择与性能不要总是查询所有字段fieldsall。只请求你需要的字段如fieldsspend,impressions,clicks,cpc。这能显著提升API响应速度和减少数据处理负担。Meta API有些字段是默认不返回的如actions需要显式指定。分页处理当AI返回的数据说“以下是前25条结果”时意味着还有更多。你可以直接告诉AI“请获取下一页结果”或“获取全部结果”。AI会利用返回的paging.cursors.after值继续调用API。对于非常大的数据集可以考虑让AI先汇总关键指标而不是拉取所有明细行。5.4 错误排查与调试查看客户端日志Claude Code或Cursor通常有开发者控制台或日志文件。当AI操作失败时首先查看这里的错误信息。常见的错误包括“Invalid OAuth access token”令牌失效、“Permissions error”权限不足、“Invalid parameter”参数错误。独立测试MCP服务器你可以在终端直接运行armavita-meta-ads-mcp然后根据MCP协议手动输入一些简单的JSON请求来测试服务器是否正常响应。这有助于隔离问题是出在服务器配置还是AI客户端。权限是万恶之源95%的“API调用失败”问题都与权限有关。请反复确认你的应用已添加了所需的产品Marketing API系统用户或访问令牌已授予了必要的权限ads_management,ads_read等并且该令牌有权访问你指定的广告账户资产层级授权。6. 安全须知与项目边界最后必须强调一下安全和项目适用范围这直接关系到你的账户安全和数据隐私。本地运行数据不出境这是本项目最大的安全优势。你的Meta访问令牌和所有广告数据只在你的电脑和Meta服务器之间传输不经过ArmaVita或任何第三方服务器。服务器代码是开源的你可以审查。令牌保护无论是环境变量还是配置文件都要像保护密码一样保护你的META_ACCESS_TOKEN、META_APP_SECRET。切勿提交到公开仓库。考虑使用.env文件通过python-dotenv加载并加入.gitignore。最小权限原则在Meta开发者平台为你的应用或系统用户授予权限时只授予它完成必要功能所需的最小权限。例如如果只是读数据就不要给ads_management权限。项目边界清晰这是一个本地MCP服务器仅支持stdio传输模式。它不是一个SaaS服务没有Web界面也不提供远程访问。它的功能完全围绕Meta Marketing API封装不处理其他平台如Google Ads, TikTok Ads的API。这意味着它的能力深度和Meta API保持一致但广度仅限于此。使用这个工具就像是给你的AI助手配备了一套专业的Meta广告操作面板。它不能替代你的策略思考和创意判断但能极大地解放你在数据获取、重复操作和初步分析上的生产力。刚开始配置可能会遇到一些门槛但一旦跑通你会发现这种“用自然语言指挥AI操作专业系统”的工作流其流畅感和效率提升是革命性的。我个人最喜欢用它来做每日数据快览和A/B测试的初步设置把节省下来的时间用在更重要的广告策略优化和创意构思上。
