Conector MCP de Meta

Servidor MCP en lenguaje natural para Meta / Facebook Ads mediante la Graph API.

Pregunta sobre cuentas publicitarias, campañas, conjuntos de anuncios, gasto y rendimiento en lenguaje natural, sin necesidad de nombres de tablas ni rutas de API sin procesar.

Características

• Datos en vivo de la API de Marketing de Facebook (Graph API)

• Lista de cuentas publicitarias con el Business Manager principal

• Rendimiento de campañas / conjuntos de anuncios / anuncios (gasto, impresiones, clics, compras)

• Panel de gasto a nivel de cuenta (account-spend.html)

• OAuth de Claude.ai cuando se implementa en Cloud Run (MCP_PUBLIC_URL)

Related MCP server: Instagram Ads MCP Server

Estructura del proyecto

meta-mcp-connector/
├── meta_mcp_server.py    # MCP server + HTTP routes + tools
├── meta_graph.py         # Facebook Graph API client
├── meta_oauth.py         # Claude-compatible OAuth provider
├── account-spend.html    # Spend-by-account dashboard
├── test-accounts.html    # Ad account list test page
├── get-token.html        # Helper to obtain FACEBOOK_ACCESS_TOKEN
├── requirements.txt
├── Dockerfile
├── deploy-cloudrun.ps1   # Deploy to Google Cloud Run
├── .env.example
└── .cursor/mcp.json      # Local Cursor MCP config (example)

Configuración (local)

1. Clonar e instalar

git clone https://github.com/YOUR_USERNAME/meta-mcp-connector.git
cd meta-mcp-connector
python -m venv .venv

# Windows
.venv\Scripts\activate

pip install -r requirements.txt
copy .env.example .env

2. Configurar .env

FACEBOOK_APP_ID=your_app_id
FACEBOOK_APP_SECRET=your_app_secret
FACEBOOK_ACCESS_TOKEN=your_user_token_with_ads_read
FACEBOOK_AD_ACCOUNT_ID=114810198697538

Requisitos del token

• Debe ser un Token de usuario (EAA…), no un Token de aplicación (app_id|secret)

• Generado en el Explorador de Graph API para tu FACEBOOK_APP_ID

• Permisos: ads_read, ads_management, business_management

Usa get-token.html o ejecuta el servidor y abre http://127.0.0.1:8001/get-token.

3. Iniciar el servidor

python meta_mcp_server.py --http

4. Configuración de MCP en Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "meta": {
      "url": "http://127.0.0.1:8001/mcp"
    }
  }
}

Recarga MCP en la configuración de Cursor después de iniciar el servidor.

Herramientas MCP

Ejemplos de consultas

• "Lista mis cuentas publicitarias de Meta"

• "Resumen de anuncios de Meta del 2026-08-01 al 2026-08-15"

• "Gasto diario de los últimos 7 días para WOW Ad Account"

• "Anuncios principales por gasto ayer"

• "Desglosa el gasto por campaña la semana pasada"

Google Cloud Run

Aloja el mismo endpoint MCP HTTP en Cloud Run (mismo patrón que vdp-connector). La imagen de Docker no incluye .env ni secretos.

Requisitos previos

• Google Cloud SDK (gcloud) instalado y con sesión iniciada (gcloud auth login)

• Un proyecto de GCP con facturación habilitada

• Tu ID de proyecto de GCP

• Credenciales de Facebook listas en .env local (ver .env.example)

Implementación

Desde la carpeta de este repositorio:

# App secret read from .env
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID"

# Optional overrides
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -Region "us-central1" -Service "meta-mcp"

# App secret from a one-line file (gitignored)
.\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID" -SecretFile ".\facebook-app-secret.key"

Qué hace el script:

1. Habilita Cloud Run, Cloud Build, Secret Manager, Artifact Registry

2. Sube FACEBOOK_APP_SECRET → Secret Manager (meta-facebook-app-secret)

3. Sube FACEBOOK_ACCESS_TOKEN → Secret Manager (meta-facebook-access-token) si está configurado en .env

4. Implementa con --source . (Dockerfile), variables de entorno e inyección de secretos

5. Establece MCP_PUBLIC_URL a la URL del servicio (requerido para OAuth de Claude)

6. Imprime la URL del conector: https://SERVICE-URL/mcp

Banderas de implementación:

• --set-env-vars MCP_TRANSPORT=http,HOST=0.0.0.0,FACEBOOK_APP_ID=…,FACEBOOK_AD_ACCOUNT_ID=…

• --set-secrets FACEBOOK_APP_SECRET=meta-facebook-app-secret:latest,FACEBOOK_ACCESS_TOKEN=meta-facebook-access-token:latest

• --allow-unauthenticated (necesario para una URL MCP funcional en la primera implementación)

• --session-affinity, --max-instances 1, --timeout 300, --port 8080

Cursor (Cloud Run)

Después de implementar, coloca la URL impresa en .cursor/mcp.json:

"meta": {
  "url": "https://YOUR-CLOUD-RUN-URL/mcp"
}

No necesitas un proceso local python meta_mcp_server.py cuando usas Cloud Run.

Conector personalizado de Claude

Claude.ai requiere OAuth para conectores personalizados remotos. Este servidor incluye un proveedor OAuth compatible con Claude (Registro dinámico de clientes) cuando MCP_PUBLIC_URL está configurado (el script de implementación lo establece automáticamente).

1. Implementa con .\deploy-cloudrun.ps1 -ProjectId "YOUR_GCP_PROJECT_ID"

2. Elimina cualquier conector antiguo roto

3. Configuración → Conectores → Agregar conector personalizado

4. Pega exactamente: https://YOUR-CLOUD-RUN-URL/mcp (debe incluir /mcp)

5. Deja OAuth Client ID vacío en la configuración avanzada (DCR está habilitado)

6. Haz clic en Conectar — Claude se registra y autoriza brevemente

Si ves "Couldn't register with … sign-in service" (ofid_…):

• Confirma que la URL termina con /mcp (no el host de Cloud Run sin la ruta)

• Confirma que el servicio está activo: abre https://YOUR-CLOUD-RUN-URL/.well-known/oauth-authorization-server — deberías ver JSON con registration_endpoint

• Confirma que MCP_PUBLIC_URL coincide con el origen del servicio (reimplementa si cambiaste la URL)

• No pegues un OAuth Client ID aleatorio a menos que hayas configurado un IdP externo

Verificar la implementación

Local vs Cloud

Nota de seguridad

--allow-unauthenticated hace que la URL de Cloud Run sea accesible públicamente. OAuth significa que Claude debe completar el registro/autorización antes de que funcionen las herramientas; los llamadores aleatorios sin token obtienen 401. Aun así, trata la URL como sensible y agrega autenticación más fuerte antes de compartirla ampliamente.

Errores comunes

1. URL de Claude sin /mcp → "Couldn't connect to the server"

2. MCP_PUBLIC_URL no configurado → OAuth 404 → "Couldn't register with sign-in service"

3. Confirmar .env o archivos de secretos

4. Olvidar reimplementar después de cambios en el código OAuth

5. Implementar sin FACEBOOK_ACCESS_TOKEN → la Graph API devuelve errores de permisos

Push a GitHub

# Sign in to your new GitHub account first
git credential-manager github login --force

# Create repo on GitHub (browser or gh), then:
git remote add origin https://github.com/YOUR_USERNAME/meta-mcp-connector.git
git add .
git commit -m "Initial commit: Meta MCP connector"
git push -u origin main

Seguridad

• Nunca confirmes .env — está en gitignore

• FACEBOOK_ACCESS_TOKEN es un secreto; rota si se expone

• La implementación en Cloud Run usa --allow-unauthenticated para la accesibilidad de la URL MCP; OAuth protege el acceso a las herramientas cuando MCP_PUBLIC_URL está configurado