Meta Ads MCP Deployment

Meta Ads MCP 代理 - 部署指南

此存储库包含用于在Ubuntu服务器上安装Meta Ads MCP（模型上下文协议）代理的自动化部署脚本和文档。

概述

Meta广告MCP代理是一个基于人工智能的界面，用于管理和优化在Facebook、Instagram以及其他Meta平台上的广告活动。此部署包提供了一个简化的安装流程，能够自动处理所有依赖项和配置。

系统要求

• 操作系统Ubuntu 24.04 LTS（已测试）或 Ubuntu 22.04 LTS
• python3.8或更高版本（自动安装）
• RAM（随机存取存储器）建议至少1GB
• 磁盘空间至少500MB可用空间
• 网络安装时需要互联网连接
• 特权需要获取Root权限

快速入门

一键安装

wget -O - https://raw.githubusercontent.com/mikee-ai/meta-ads-mcp-deployment/master/install-fixed.sh | bash

手动安装

1. 克隆这个仓库：

   git clone https://github.com/mikee-ai/meta-ads-mcp-deployment.git
   cd meta-ads-mcp-deployment

1. 运行安装脚本:

   chmod +x install.sh
   sudo ./install.sh

1. 配置身份验证:

   nano /root/.meta-ads-mcp.env

添加您的Pipeboard API令牌或Meta应用程序凭据。

1. 加载环境变量:

   source /root/.meta-ads-mcp.env

1. 验证安装:

   meta-ads-mcp --version

认证设置

您有两种身份验证选项：

选项1：管道板认证（推荐）

Pipeboard提供了一种简化的OAuth流程，以处理Meta API认证的所有复杂性。

1. 在……注册 Pipeboard.co（可译为“管道板网”或根据具体语境调整为更贴切的名称，但直接翻译即为“管道板.公司”或“管道板网站”，具体取决于该网站的实际内容和功能）
2. 在以下位置生成API令牌： pipeboard.co/api-tokens 翻译为中文是：“pipeboard.co 的 API 令牌”或“pipeboard.co 的应用程序编程接口令牌”
3. 添加到 /root/.meta-ads-mcp.env：

   PIPEBOARD_API_TOKEN=your_pipeboard_token_here

选项2：直接Meta应用认证

如果您更倾向于使用您自己的Meta开发者应用：

1. 在（指定平台）创建一个Meta开发者应用 developers.facebook.com/apps 的中文翻译是：“Facebook开发者平台 - 应用程序”
2. 配置OAuth设置和权限
3. 添加到 /root/.meta-ads-mcp.env：

   META_APP_ID=your_meta_app_id
   META_APP_SECRET=your_meta_app_secret

如需详细说明，请参阅 CUSTOM_META_APP.md 翻译为中文是：“自定义元数据应用.md” 或者更简洁地表述为 “自定义应用元数据.md”（具体翻译可能根据上下文有所调整，但核心意思是关于自定义应用元数据的文件）

安装详情

脚本的作用

自动化安装脚本执行以下操作：

1. 系统更新更新软件包列表并安装安全补丁
2. 依赖项安装安装Python 3、pip、开发工具和git
3. 仓库克隆克隆官方的Meta Ads MCP仓库
4. 软件包安装安装包含所有依赖项的Python包
5. 配置设置创建环境配置模板
6. 服务创建设置 systemd 服务以启用可选的守护进程模式
7. 验证确认安装成功

已知问题及解决方案

问题1：typing-extensions 冲突

问题Debian/Ubuntu 系统预装有 typing-extensions 与 pip 安装冲突的软件包。

解决方案该脚本使用 --ignore-installed typing-extensions 标志以绕过此冲突。

问题2：系统包管理器警告

问题全局安装 pip 包时会触发与 apt 冲突的警告。

解决方案该脚本使用 --break-system-packages 标志（专用于专用服务器，安全无虞）或者另可创建虚拟环境。

问题3：Root用户警告

问题以 root 用户身份运行 pip 会生成有关权限的警告。

解决方案这些警告仅用于提供信息，并在脚本输出中被过滤掉。在生产环境中，请考虑使用专用用户帐户。

使用示例

基本命令行用法

# Check version
meta-ads-mcp --version

# Run in interactive mode
meta-ads-mcp

# Run with specific configuration
PIPEBOARD_API_TOKEN=your_token meta-ads-mcp

作为系统服务运行

# Enable service to start on boot
systemctl enable meta-ads-mcp

# Start the service
systemctl start meta-ads-mcp

# Check service status
systemctl status meta-ads-mcp

# View service logs
journalctl -u meta-ads-mcp -f

# Stop the service
systemctl stop meta-ads-mcp

# Disable service
systemctl disable meta-ads-mcp

与MCP客户端的集成

Meta Ads MCP代理可以与各种AI客户端集成：

Claude Desktop（可译为“Claude桌面版”或保持原样，若“Claude”为特定软件或系统的名称，则通常不翻译）

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)：

{
  "mcpServers": {
    "meta-ads": {
      "command": "meta-ads-mcp",
      "env": {
        "PIPEBOARD_API_TOKEN": "your_pipeboard_token"
      }
    }
  }
}

Cursor 集成开发环境（IDE）

添加到 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "meta-ads": {
      "command": "meta-ads-mcp",
      "env": {
        "PIPEBOARD_API_TOKEN": "your_pipeboard_token"
      }
    }
  }
}

高级配置

环境变量

自定义安装目录

要在自定义目录中安装，请修改 INSTALL_DIR 脚本中的变量：

INSTALL_DIR="/opt/meta-ads-mcp"

虚拟环境安装

对于独立的Python环境（推荐用于生产环境）：

# Create virtual environment
python3 -m venv /opt/meta-ads-venv

# Activate virtual environment
source /opt/meta-ads-venv/bin/activate

# Install package
pip install meta-ads-mcp

# Update systemd service to use venv
# Modify ExecStart in /etc/systemd/system/meta-ads-mcp.service:
# ExecStart=/opt/meta-ads-venv/bin/meta-ads-mcp

故障排除

安装失败

1. 检查Python版本：

   python3 --version

应该是3.8或更高。

1. 检查网络连接：

   ping -c 3 github.com

1. 检查磁盘空间：

   df -h

1. 查看安装日志：

   ./install.sh 2>&1 | tee install.log

服务无法启动

1. 检查服务状态：

   systemctl status meta-ads-mcp

1. 查看详细日志：

   journalctl -u meta-ads-mcp -n 50 --no-pager

1. 验证环境文件：

   cat /root/.meta-ads-mcp.env

1. 手动执行测试：

   source /root/.meta-ads-mcp.env
   meta-ads-mcp --version

身份验证问题

1. 验证令牌是否已设置：

   echo $PIPEBOARD_API_TOKEN

1. 测试API连接性：

   curl -H "Authorization: Bearer $PIPEBOARD_API_TOKEN" https://api.pipeboard.co/health

1. 检查元API权限确保您的Meta应用已获得所需的权限：

- ads_management - ads_read - business_management

卸载

要彻底移除Meta Ads MCP代理：

# Stop and disable service
systemctl stop meta-ads-mcp
systemctl disable meta-ads-mcp

# Remove service file
rm /etc/systemd/system/meta-ads-mcp.service
systemctl daemon-reload

# Uninstall package
pip3 uninstall meta-ads-mcp -y

# Remove installation directory
rm -rf /root/meta-ads-mcp

# Remove configuration
rm /root/.meta-ads-mcp.env

安全考量

1. API令牌安全永远不要将API令牌提交到版本控制系统中
2. 文件权限确保 .meta-ads-mcp.env 拥有受限权限：

   chmod 600 /root/.meta-ads-mcp.env

1. 网络安全考虑使用防火墙规则来限制访问
2. 定期更新保持软件包更新以应用安全补丁：

   pip3 install --upgrade meta-ads-mcp

支持与资源

• 官方仓库: Pipeboard-co/meta-ads-mcp 可以翻译为：“管道板公司（或类似名称）- 元广告-MCP（多渠道程序/机制等，具体根据上下文确定）”。不过，这里的“pipeboard-co”可能是一个特定公司或项目的名称，没有直接的中文对应，所以翻译时保留了其原样，并在后面加上了解释性说明。如果“pipeboard-co”有具体的中文名称或背景，应替换为相应的中文表述。同时，“meta-ads”翻译为“元广告”，“mcp”则根据上下文可能有不同的翻译，如“多渠道程序”、“机制控制程序”等，这里采用了较为通用的“MCP（多渠道程序/机制等）”作为翻译
• 文档： LOCAL_INSTALLATION.md 翻译为中文是：“本地安装说明.md” 或 “本地安装指南.md”（具体取决于上下文，“INSTALLATION”在这里更常被翻译为“安装”，而“.md”表示这是一个Markdown格式的文件）
• Discord社区： 加入Discord
• 电子邮件支持support@pipeboard.co 的中文翻译可以是：“support@管道板公司.com” 或者更简洁地表述为 “管道板公司支持邮箱”。不过，具体翻译可能还需根据“pipeboard”在实际业务中的具体含义来调整，如果“pipeboard”是一个特定品牌或公司名，可能需要查找其官方中文名称来进行更准确的翻译。在这里，我假设“pipeboard”是泛指与管道或板材相关的业务或产品，因此采用了较为通用的翻译方式
• 问题追踪器:

特点/功能

Meta Ads MCP代理提供以下功能：

• 活动分析基于人工智能的广告活动效果分析
• 战略建议数据支持的优化建议
• 自动化监控跟踪指标并检测显著变化
• 预算优化智能预算重新分配建议
• 创意改进对广告文案和创意元素的反馈
• 动态创意测试支持具有多个变体的A/B测试
• 活动管理通过编程方式创建、更新和管理营销活动
• 跨平台支持与Facebook、Instagram以及所有Meta平台兼容
• 通用大型语言模型支持兼容Claude、GPT及其他MCP客户端

API 工具可用

该代理提供了以下MCP工具：

• mcp_meta_ads_get_ad_accounts - 列出可访问的广告账户
• mcp_meta_ads_get_account_info - 获取详细的账户信息
• mcp_meta_ads_get_account_pages - 列出与账户关联的页面
• mcp_meta_ads_get_campaigns - 列出并过滤活动
• mcp_meta_ads_get_campaign_details - 获取详细的活动信息
• mcp_meta_ads_create_campaign - 创建新活动
• mcp_meta_ads_update_campaign - 更新现有活动
• mcp_meta_ads_get_ad_sets - 列出广告系列
• mcp_meta_ads_create_ad_set - 创建新的广告系列
• mcp_meta_ads_get_ads - 列出广告
• mcp_meta_ads_create_ad - 创建新广告
• mcp_meta_ads_get_insights - 获取性能见解
• 还有很多其他的。。。

如需完整的API文档，请参阅 官方README文件.

许可证

此部署包提供原样，以便于安装Meta Ads MCP代理。

Meta Ads MCP代理本身根据商业源代码许可证1.1获得授权。请参阅 许可证 在官方仓库中提交文件。

做出贡献

欢迎为改进部署流程做出贡献！请向本仓库提交问题或拉取请求。

更新日志

版本 1.0.0（2025年10月21日）

• 首次发布
• 适用于Ubuntu 24.04 LTS的自动化安装脚本
• Systemd服务配置
• 全面的文档记录
• 常见安装问题的错误处理

免责声明

这是一个非官方的第三方部署工具，与Meta或Pipeboard无关，既未得到它们的认可，也未与它们有任何关联。此项目独立维护，旨在简化Meta Ads MCP代理的安装过程。