# Meta Ads MCP Server

Un servidor MCP (Model Context Protocol) que conecta a Claude con la **Meta Marketing API** para analizar y gestionar tus campañas de Facebook/Instagram Ads.

## ✨ Herramientas Disponibles

| Herramienta | Descripción |
|---|---|
| `meta_get_ad_accounts` | Lista tus cuentas de anuncios |
| `meta_get_campaigns` | Lista campañas con filtros por estado |
| `meta_get_campaign_details` | Detalles completos de una campaña |
| `meta_get_adsets` | Lista conjuntos de anuncios |
| `meta_get_ads` | Lista anuncios individuales |
| `meta_get_insights` | 📊 Métricas de rendimiento (spend, ROAS, CTR, etc.) |
| `meta_update_campaign_status` | Pausar/activar campañas |
| `meta_update_adset_status` | Pausar/activar ad sets |

## 🚀 Setup

### 1. Prerequisitos

- **Node.js 18+**
- **Meta Developer App** con acceso a la Marketing API
- **Access Token** con permisos `ads_read` (mínimo) o `ads_management` (para pausar/activar)

### 2. Obtener credenciales de Meta

1. Ve a [Meta for Developers](https://developers.facebook.com/) y crea una app (tipo "Business")
2. Agrega el producto **Marketing API**
3. Ve al [Graph API Explorer](https://developers.facebook.com/tools/explorer/) y genera un token con el permiso `ads_read`
4. Tu Ad Account ID lo encuentras en [Meta Business Manager](https://business.facebook.com/) → Configuración → Cuentas publicitarias

### 3. Compilar

```bash
cd mcp-meta
npm install
npm run build
```

### 4. Configurar en Claude Desktop

Edita tu archivo de configuración de Claude Desktop:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "meta-ads": {
      "command": "node",
      "args": ["c:\\Users\\agus2\\Desktop\\mcp-meta\\dist\\index.js"],
      "env": {
        "META_ACCESS_TOKEN": "TU_TOKEN_AQUI",
        "META_AD_ACCOUNT_ID": "act_XXXXXXXXX"
      }
    }
  }
}
```

### 5. Reiniciar Claude Desktop

Reinicia Claude Desktop y verás las herramientas de Meta disponibles.

## 💬 Ejemplos de uso

Una vez configurado, puedes preguntarle a Claude:

- *"Muéstrame mis campañas activas"*
- *"¿Cuánto he gastado esta semana?"*
- *"¿Cuál es el ROAS de mi campaña X en los últimos 30 días?"*
- *"Muéstrame el rendimiento por grupo de edad"*
- *"Dame el CTR diario de la última semana"*
- *"Pausa la campaña 123456"*

## 📊 Insights — Métricas disponibles

La herramienta `meta_get_insights` soporta:

**Métricas**: spend, impressions, reach, clicks, CPC, CPM, CTR, frequency, ROAS, conversions, cost per conversion

**Rangos de fecha**: today, yesterday, last_7d, last_14d, last_30d, last_90d, this_month, last_month, o rango personalizado

**Granularidad temporal**: diario, semanal, mensual

**Breakdowns**: edad, género, país, placement, dispositivo

## 🔐 Seguridad

- Tu access token se pasa solo como variable de entorno, nunca se almacena en código
- El servidor corre localmente via stdio — no expone ningún puerto de red
- Usa permisos `ads_read` para solo lectura (recomendado inicialmente)

## 🛠 Desarrollo

```bash
# Desarrollo con hot-reload
npm run dev

# Build de producción
npm run build

# Testear con MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js
```