Meta Ads MCP

Convierte la API de Graph de Meta (Facebook) Ads en un servidor MCP para que Claude (Desktop / Claude Code) pueda llamarla directamente, de modo que los compañeros de la empresa puedan consultar el rendimiento de los anuncios y los materiales creativos mediante conversación.

Las dos API correspondientes a la especificación del PDF:

Dos formas de ejecución

A. Local (stdio)

Related MCP server: Meta Ads MCP Server

Instalación

cd C:\Users\bexo6\OneDrive\桌面\mcp_meta_claude
uv sync
Copy-Item .env.example .env   # 然後填好 META_ACCESS_TOKEN 等

Conectar con Claude Desktop

Edita %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "meta-ads": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\bexo6\\OneDrive\\桌面\\mcp_meta_claude",
        "run",
        "python",
        "server.py"
      ]
    }
  }
}

Reinicia Claude Desktop → Settings → Developer deberías ver meta-ads.

B. Desplegar en EC2 para uso de toda la empresa (http)

Se asume que ya tienes EC2 + nginx + HTTPS ejecutándose en https://ai.gastom.com.tw. No instalamos Caddy adicionalmente, solo ejecutamos el contenedor MCP (vinculado a 127.0.0.1:8000), para que tu nginx existente redirija https://ai.gastom.com.tw/meta-ads/* hacia él.

1. Generar el token Bearer compartido

python3 -c "import secrets; print(secrets.token_urlsafe(32))"

Guarda la cadena (gestor de contraseñas / vault de la empresa). Luego:

• Escríbela en el .env del EC2

• Envíala a los compañeros para que la pongan en Claude Desktop

2. Colocar el código en el EC2

ssh your-user@ec2-host
git clone <你的 repo 位置> meta-ads-mcp
cd meta-ads-mcp

cat > .env <<'EOF'
META_ACCESS_TOKEN=<長效 Graph API token>
META_AD_ACCOUNT_ID=act_870176260326362
MCP_BEARER_TOKEN=<上一步產生的字串>
EOF
chmod 600 .env

3. Iniciar el contenedor MCP

docker compose up -d --build
docker compose logs -f mcp     # 看到 "Uvicorn running on http://0.0.0.0:8000" 就 OK

Verifica desde el propio EC2 (aún sin pasar por nginx):

curl -i http://127.0.0.1:8000/healthz                # 200
curl -i -X POST http://127.0.0.1:8000/mcp            # 401（沒 token）

4. Añadir una location en nginx

Pega el contenido de deploy/nginx-meta-ads.conf dentro del bloque existente server { listen 443 ssl; server_name ai.gastom.com.tw; ... }, y luego:

sudo nginx -t                # 語法檢查
sudo systemctl reload nginx  # 套用

Verifica desde la red externa:

curl -i https://ai.gastom.com.tw/meta-ads/healthz                  # 200
curl -i -X POST https://ai.gastom.com.tw/meta-ads/mcp              # 401
curl -i -X POST -H "Authorization: Bearer <你的token>" \
     -H "Accept: application/json, text/event-stream" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
     https://ai.gastom.com.tw/meta-ads/mcp                          # 200 + serverInfo

5. Configuración de Claude Desktop para los compañeros

Cada compañero añade en %APPDATA%\Claude\claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "meta-ads": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://ai.gastom.com.tw/meta-ads/mcp",
        "--header",
        "Authorization: Bearer 上面產生的_MCP_BEARER_TOKEN"
      ]
    }
  }
}

La computadora de los compañeros debe tener Node.js (para que npx funcione). mcp-remote hace de puente entre stdio y tu endpoint HTTPS; ellos no necesitan instalar Python / uv / tu código.

Proceso de actualización / renovación

cd /path/to/meta-ads-mcp
git pull
docker compose up -d --build

Apagar

docker compose down

Rotación de token

Cuando el token se filtre o se renueve periódicamente:

1. Cambia MCP_BEARER_TOKEN en el .env del EC2

2. docker compose up -d (recreará el contenedor mcp)

3. Envía el nuevo token a los compañeros y actualiza su claude_desktop_config.json

Ejemplos de conversación

«Ayúdame a obtener los datos de anuncios del 2026-03-23 al 2026-03-25 y lista los tres anuncios con mayor gasto»

«Ayúdame a ver cómo es el material creativo del anuncio con ID 120228265609960545»

Claude decidirá por sí mismo llamar primero a get_ad_insights y luego a get_ad_creative para el ad_id específico.

Notas de seguridad

• Nunca hagas commit del .env: .gitignore ya lo bloquea.

• MCP_BEARER_TOKEN es la llave del presupuesto de la empresa: quien lo obtenga puede llamar a la API de Meta y gastar el dinero de publicidad de tu empresa. Trátalo con el mismo nivel de seguridad que una contraseña.

• HTTPS es imprescindible: enviar el token Bearer por HTTP equivale a transmitirlo en texto plano.

• Security Group del EC2: además de abrir 80/443 al exterior, se recomienda restringir los demás puertos (especialmente el 22) al rango de IP de la empresa.