# MCP DataForSEO Server

Servidor MCP que expone la API de DataForSEO como herramientas globales para Claude Code.

**Version:** 2.1.0

## Herramientas Disponibles (24)

### Herramientas Basicas (5)

| Herramienta | Descripcion | API Requerida |
|-------------|-------------|---------------|
| `check_serp_position` | Posicion actual de un dominio para una keyword | SERP API |
| `research_keywords` | Volumen de busqueda y metricas de keywords | Keywords Data API |
| `get_backlinks_summary` | Resumen del perfil de backlinks | Backlinks API |
| `find_competitors` | Competidores SEO por backlinks compartidos | Backlinks API |
| `get_domain_rank` | Domain Rank (autoridad) de un dominio | Backlinks API |

### DataForSEO Labs - Keyword Research (5) - NUEVO

| Herramienta | Descripcion | API Requerida |
|-------------|-------------|---------------|
| `get_keyword_difficulty` | Dificultad de posicionamiento (0-100) | DataForSEO Labs API |
| `get_keyword_suggestions` | Sugerencias de keywords relacionadas | DataForSEO Labs API |
| `get_search_intent` | Clasificacion de intencion de busqueda | DataForSEO Labs API |
| `get_ranked_keywords` | Todas las keywords que posiciona un dominio | DataForSEO Labs API |
| `get_serp_competitors` | Competidores por overlap de keywords | DataForSEO Labs API |

### OnPage & Lighthouse (2) - NUEVO

| Herramienta | Descripcion | API Requerida |
|-------------|-------------|---------------|
| `analyze_page_seo` | Auditoria SEO on-page instantanea | OnPage API |
| `get_page_lighthouse` | Core Web Vitals y metricas Lighthouse | OnPage API |

### Backlinks Avanzados (3) - NUEVO

| Herramienta | Descripcion | API Requerida |
|-------------|-------------|---------------|
| `get_anchor_texts` | Distribucion de anchor texts | Backlinks API |
| `get_new_lost_backlinks` | Backlinks ganados y perdidos en periodo | Backlinks API |
| `get_referring_domains` | Lista detallada de dominios que enlazan | Backlinks API |

### Contenido y Tendencias (3)

| Herramienta | Descripcion | API Requerida |
|-------------|-------------|---------------|
| `analyze_content_sentiment` | Sentimiento de contenido para keyword | Content Analysis API |
| `get_keyword_trends` | Datos de Google Trends | Keywords Data API |
| `get_domain_technologies` | Tecnologias detectadas en un dominio | Domain Analytics API |

### Analisis Avanzado (6) - NUEVO v2.1.0

| Herramienta | Descripcion | API Requerida |
|-------------|-------------|---------------|
| `get_domain_intersection` | Keywords compartidas entre dos dominios | DataForSEO Labs API |
| `estimate_traffic` | Estimacion de trafico organico para dominios | DataForSEO Labs API |
| `get_keywords_for_site` | Keywords que un sitio targeta (basado en contenido) | DataForSEO Labs API |
| `get_historical_rank` | Ranking historico de un dominio | DataForSEO Labs API |
| `get_keyword_ideas` | Ideas de keywords a partir de seeds | DataForSEO Labs API |
| `get_related_keywords` | Keywords semanticamente relacionadas | DataForSEO Labs API |

---

## Ejemplos de Uso

### Keyword Research

#### get_keyword_difficulty
```
mcp__dataforseo__get_keyword_difficulty(
  keywords=["neon personalizado", "letrero led", "cartel luminoso"],
  country_code="ES"
)
```

**Respuesta:**
```json
{
  "country": "ES",
  "keywords": [
    {
      "keyword": "neon personalizado",
      "keyword_difficulty": 42,
      "search_volume": 1900,
      "competition_level": "MEDIUM"
    },
    {
      "keyword": "letrero led",
      "keyword_difficulty": 58,
      "search_volume": 3200,
      "competition_level": "HIGH"
    }
  ]
}
```

#### get_keyword_suggestions
```
mcp__dataforseo__get_keyword_suggestions(
  seed_keyword="neon personalizado",
  country_code="ES",
  limit=10
)
```

**Respuesta:**
```json
{
  "seed_keyword": "neon personalizado",
  "suggestions": [
    {
      "keyword": "neon personalizado con nombre",
      "search_volume": 480,
      "keyword_difficulty": 35,
      "cpc": 0.52
    },
    {
      "keyword": "neon personalizado barato",
      "search_volume": 320,
      "keyword_difficulty": 28,
      "cpc": 0.41
    }
  ]
}
```

#### get_search_intent
```
mcp__dataforseo__get_search_intent(
  keywords=["comprar neon personalizado", "como hacer neon casero", "neon personalizado"],
  country_code="ES"
)
```

**Respuesta:**
```json
{
  "keywords": [
    {
      "keyword": "comprar neon personalizado",
      "search_intent": "transactional",
      "intent_probability": 0.92
    },
    {
      "keyword": "como hacer neon casero",
      "search_intent": "informational",
      "intent_probability": 0.88
    },
    {
      "keyword": "neon personalizado",
      "search_intent": "commercial",
      "intent_probability": 0.75
    }
  ]
}
```

#### get_ranked_keywords
```
mcp__dataforseo__get_ranked_keywords(
  domain="espacioneon.com",
  country_code="ES",
  limit=20
)
```

**Respuesta:**
```json
{
  "domain": "espacioneon.com",
  "total_count": 1250,
  "keywords": [
    {
      "keyword": "neon personalizado",
      "position": 8,
      "url": "https://espacioneon.com/producto/neon-personalizado/",
      "search_volume": 1900,
      "cpc": 0.45
    }
  ]
}
```

#### get_serp_competitors
```
mcp__dataforseo__get_serp_competitors(
  keywords=["neon personalizado", "letrero neon", "neon led"],
  country_code="ES",
  limit=10
)
```

**Respuesta:**
```json
{
  "keywords": ["neon personalizado", "letrero neon", "neon led"],
  "competitors": [
    {
      "domain": "neonsigns.es",
      "avg_position": 4.2,
      "intersections": 3
    },
    {
      "domain": "letrerosneon.com",
      "avg_position": 6.8,
      "intersections": 3
    }
  ]
}
```

---

### OnPage & Lighthouse

#### analyze_page_seo
```
mcp__dataforseo__analyze_page_seo(url="https://espacioneon.com/producto/neon-personalizado/")
```

**Respuesta:**
```json
{
  "url": "https://espacioneon.com/producto/neon-personalizado/",
  "status_code": 200,
  "title": "Neon Personalizado - Disena tu Letrero LED | EspacioNeon",
  "meta_description": "Crea tu neon personalizado online...",
  "h1": ["Neon Personalizado"],
  "word_count": 1250,
  "images_count": 8,
  "images_without_alt": 2,
  "internal_links": 45,
  "external_links": 3,
  "load_time": 2.3,
  "errors": [],
  "warnings": ["no_image_alt: 2"]
}
```

#### get_page_lighthouse
```
mcp__dataforseo__get_page_lighthouse(
  url="https://espacioneon.com/",
  device="mobile"
)
```

**Respuesta:**
```json
{
  "url": "https://espacioneon.com/",
  "device": "mobile",
  "scores": {
    "performance": 72,
    "accessibility": 88,
    "best-practices": 92,
    "seo": 95
  },
  "core_web_vitals": {
    "largest-contentful-paint": {
      "score": 65,
      "value": "2.8 s",
      "numeric_value": 2800
    },
    "cumulative-layout-shift": {
      "score": 95,
      "value": "0.05",
      "numeric_value": 0.05
    },
    "total-blocking-time": {
      "score": 70,
      "value": "320 ms",
      "numeric_value": 320
    }
  },
  "opportunities": [
    {
      "id": "render-blocking-resources",
      "title": "Eliminate render-blocking resources",
      "savings": 850
    }
  ]
}
```

---

### Backlinks Avanzados

#### get_anchor_texts
```
mcp__dataforseo__get_anchor_texts(domain="espacioneon.com", limit=20)
```

**Respuesta:**
```json
{
  "domain": "espacioneon.com",
  "total_anchors": 187,
  "anchors": [
    {
      "anchor": "espacioneon",
      "backlinks": 45,
      "referring_domains": 38
    },
    {
      "anchor": "neon personalizado",
      "backlinks": 28,
      "referring_domains": 22
    },
    {
      "anchor": "click here",
      "backlinks": 12,
      "referring_domains": 10
    }
  ]
}
```

#### get_new_lost_backlinks
```
mcp__dataforseo__get_new_lost_backlinks(
  domain="espacioneon.com",
  date_from="2026-01-01",
  date_to="2026-02-01"
)
```

**Respuesta:**
```json
{
  "domain": "espacioneon.com",
  "date_from": "2026-01-01",
  "date_to": "2026-02-01",
  "summary": {
    "new_backlinks": 124,
    "lost_backlinks": 38,
    "new_referring_domains": 18,
    "lost_referring_domains": 5
  },
  "timeseries": [
    {
      "date": "2026-01-15",
      "new_backlinks": 8,
      "lost_backlinks": 2
    }
  ]
}
```

#### get_referring_domains
```
mcp__dataforseo__get_referring_domains(
  domain="espacioneon.com",
  limit=10,
  order_by="rank"
)
```

**Respuesta:**
```json
{
  "domain": "espacioneon.com",
  "total_referring_domains": 187,
  "referring_domains": [
    {
      "domain": "periodico.com",
      "rank": 75,
      "backlinks": 3,
      "dofollow": 3,
      "nofollow": 0,
      "first_seen": "2025-06-15"
    }
  ]
}
```

---

### Contenido y Tendencias

#### analyze_content_sentiment
```
mcp__dataforseo__analyze_content_sentiment(keyword="neon personalizado", country_code="ES")
```

**Respuesta:**
```json
{
  "keyword": "neon personalizado",
  "sentiment_distribution": {
    "positive": 0.65,
    "neutral": 0.28,
    "negative": 0.07
  },
  "connotations": [
    {"type": "decoracion", "count": 45},
    {"type": "regalo", "count": 28},
    {"type": "negocio", "count": 22}
  ]
}
```

#### get_keyword_trends
```
mcp__dataforseo__get_keyword_trends(
  keywords=["neon personalizado", "letrero led"],
  country_code="ES"
)
```

**Respuesta:**
```json
{
  "keywords": ["neon personalizado", "letrero led"],
  "trends": [
    {
      "date": "2025-12-01",
      "values": [{"keyword": "neon personalizado", "value": 85}]
    },
    {
      "date": "2026-01-01",
      "values": [{"keyword": "neon personalizado", "value": 72}]
    }
  ]
}
```

#### get_domain_technologies
```
mcp__dataforseo__get_domain_technologies(domain="espacioneon.com")
```

**Respuesta:**
```json
{
  "domain": "espacioneon.com",
  "technologies": [
    {"name": "WordPress", "category": "CMS", "version": "6.4"},
    {"name": "WooCommerce", "category": "Ecommerce", "version": "8.2"},
    {"name": "Cloudflare", "category": "CDN"},
    {"name": "Google Analytics", "category": "Analytics"}
  ],
  "categories": {
    "CMS": ["WordPress"],
    "Ecommerce": ["WooCommerce"],
    "CDN": ["Cloudflare"],
    "Analytics": ["Google Analytics"]
  }
}
```

---

### Analisis Avanzado (NUEVO v2.1.0)

#### get_domain_intersection
```
mcp__dataforseo__get_domain_intersection(
  domain1="espacioneon.com",
  domain2="competidor.com",
  country_code="ES",
  limit=20
)
```

**Respuesta:**
```json
{
  "domain1": "espacioneon.com",
  "domain2": "competidor.com",
  "total_count": 156,
  "keywords": [
    {
      "keyword": "neon personalizado",
      "search_volume": 1900,
      "competition": 0.45,
      "cpc": 0.52,
      "domain1_position": 8,
      "domain1_url": "https://espacioneon.com/producto/neon-personalizado/",
      "domain2_position": 3,
      "domain2_url": "https://competidor.com/neon-custom/"
    },
    {
      "keyword": "letrero led personalizado",
      "search_volume": 880,
      "domain1_position": 12,
      "domain2_position": 7
    }
  ]
}
```

#### estimate_traffic
```
mcp__dataforseo__estimate_traffic(
  domains=["espacioneon.com", "competidor1.com", "competidor2.com"],
  country_code="ES"
)
```

**Respuesta:**
```json
{
  "country": "ES",
  "domains": [
    {
      "domain": "espacioneon.com",
      "estimated_traffic": 4500,
      "keywords_count": 1250,
      "estimated_cost": 2800
    },
    {
      "domain": "competidor1.com",
      "estimated_traffic": 12000,
      "keywords_count": 3400,
      "estimated_cost": 8500
    }
  ]
}
```

#### get_keywords_for_site
```
mcp__dataforseo__get_keywords_for_site(
  domain="espacioneon.com",
  country_code="ES",
  limit=20
)
```

**Respuesta:**
```json
{
  "domain": "espacioneon.com",
  "total_count": 2450,
  "keywords": [
    {
      "keyword": "neon personalizado con nombre",
      "search_volume": 480,
      "competition": 0.35,
      "cpc": 0.42,
      "keyword_difficulty": 32
    }
  ]
}
```

#### get_historical_rank
```
mcp__dataforseo__get_historical_rank(
  domain="espacioneon.com",
  country_code="ES"
)
```

**Respuesta:**
```json
{
  "domain": "espacioneon.com",
  "country": "ES",
  "history": [
    {
      "date": "2025-12-01",
      "keywords_count": 1150,
      "estimated_traffic": 3800,
      "pos_1": 12,
      "pos_2_3": 45,
      "pos_4_10": 180,
      "pos_11_20": 320
    },
    {
      "date": "2026-01-01",
      "keywords_count": 1250,
      "estimated_traffic": 4500,
      "pos_1": 15,
      "pos_2_3": 52,
      "pos_4_10": 210,
      "pos_11_20": 340
    }
  ]
}
```

#### get_keyword_ideas
```
mcp__dataforseo__get_keyword_ideas(
  keywords=["neon personalizado", "letrero led"],
  country_code="ES",
  limit=10
)
```

**Respuesta:**
```json
{
  "seed_keywords": ["neon personalizado", "letrero led"],
  "total_count": 450,
  "ideas": [
    {
      "keyword": "neon personalizado bar",
      "search_volume": 320,
      "competition": 0.28,
      "cpc": 0.38,
      "keyword_difficulty": 25,
      "search_intent": "commercial"
    },
    {
      "keyword": "letrero led cocina",
      "search_volume": 210,
      "keyword_difficulty": 22,
      "search_intent": "commercial"
    }
  ]
}
```

#### get_related_keywords
```
mcp__dataforseo__get_related_keywords(
  keyword="neon personalizado",
  country_code="ES",
  limit=10
)
```

**Respuesta:**
```json
{
  "seed_keyword": "neon personalizado",
  "total_count": 280,
  "related_keywords": [
    {
      "keyword": "cartel neon personalizado",
      "search_volume": 590,
      "competition": 0.42,
      "cpc": 0.48,
      "keyword_difficulty": 38,
      "se_type": "google",
      "depth": 1
    },
    {
      "keyword": "luz neon decorativa",
      "search_volume": 420,
      "keyword_difficulty": 35,
      "depth": 2
    }
  ]
}
```

---

## Costos Aproximados

| Categoria | Herramientas | Costo/Request |
|-----------|--------------|---------------|
| SERP API | `check_serp_position` | ~$0.002 |
| Keywords Data | `research_keywords`, `get_keyword_trends` | ~$0.005/kw |
| DataForSEO Labs | `get_keyword_*`, `get_search_intent`, `get_ranked_keywords`, `get_serp_competitors` | ~$0.003-0.010 |
| DataForSEO Labs (Advanced) | `get_domain_intersection`, `estimate_traffic`, `get_keywords_for_site`, `get_historical_rank`, `get_keyword_ideas`, `get_related_keywords` | ~$0.005-0.015 |
| Backlinks | `get_backlinks_summary`, `find_competitors`, `get_anchor_texts`, `get_referring_domains`, `get_new_lost_backlinks` | ~$0.002-0.005 |
| OnPage | `analyze_page_seo`, `get_page_lighthouse` | ~$0.005-0.015 |
| Content Analysis | `analyze_content_sentiment` | ~$0.005 |
| Domain Analytics | `get_domain_technologies` | ~$0.002 |

---

## Manejo de Errores

El servidor MCP devuelve mensajes de error claros:

### Quota Exceeded
```
⚠️ Quota Exceeded: DataForSEO quota exceeded or insufficient balance

Check your DataForSEO balance at https://app.dataforseo.com/
```

### API Not Available
```
📦 API Not Available: This API endpoint is not available in your subscription.

To activate this API:
1. Go to https://app.dataforseo.com/
2. Navigate to Billing → API Products
3. Activate the required API (pay-as-you-go)
```

### Authentication Error
```
🔐 Authentication Error: Invalid DataForSEO credentials

Verify DATAFORSEO_LOGIN and DATAFORSEO_PASSWORD environment variables.
```

---

## Requisitos de API por Herramienta

| API DataForSEO | Herramientas | Como Activar |
|----------------|--------------|--------------|
| **SERP API** | `check_serp_position` | Activado por defecto |
| **Keywords Data API** | `research_keywords`, `get_keyword_trends` | Activado por defecto |
| **DataForSEO Labs API** | `get_keyword_difficulty`, `get_keyword_suggestions`, `get_search_intent`, `get_ranked_keywords`, `get_serp_competitors`, `get_domain_intersection`, `estimate_traffic`, `get_keywords_for_site`, `get_historical_rank`, `get_keyword_ideas`, `get_related_keywords` | Billing → API Products |
| **Backlinks API** | `get_backlinks_summary`, `find_competitors`, `get_domain_rank`, `get_anchor_texts`, `get_new_lost_backlinks`, `get_referring_domains` | Billing → API Products |
| **OnPage API** | `analyze_page_seo`, `get_page_lighthouse` | Billing → API Products |
| **Content Analysis API** | `analyze_content_sentiment` | Billing → API Products |
| **Domain Analytics API** | `get_domain_technologies` | Billing → API Products |

---

## Instalacion

```bash
cd /Users/kevin/Documents/Desarrollo\ y\ Codigos/mcp-dataforseo
uv sync
```

## Configuracion en Claude Code

Agregar a `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "dataforseo": {
      "command": "uv",
      "args": ["--directory", "/Users/kevin/Documents/Desarrollo y Codigos/mcp-dataforseo", "run", "mcp-dataforseo"],
      "env": {
        "DATAFORSEO_LOGIN": "tu_login",
        "DATAFORSEO_PASSWORD": "tu_password"
      }
    }
  }
}
```

---

## Paises Soportados

ES, MX, AR, CO, US, GB, DE, FR, IT, PT, NL, BE, AT, CH, IE, PL, CZ, SE, DK, NO, FI, GR, HU, RO, BG, HR, SK, SI, LT, LV, EE, BR, CL, PE

---

## Estructura del Proyecto

```
mcp-dataforseo/
├── pyproject.toml
├── src/
│   └── mcp_dataforseo/
│       ├── __init__.py
│       ├── server.py      # Servidor MCP con 24 herramientas
│       └── client.py      # Cliente API con retry y error handling
└── README.md
```

---

## Combinacion con GSC

DataForSEO complementa GSC aportando datos que GSC no tiene:

| Necesito... | Usar |
|-------------|------|
| Posicion actual exacta (tiempo real) | DataForSEO `check_serp_position` |
| Impresiones y CTR de mi sitio | GSC `search_analytics` |
| Volumen de busqueda de keywords | DataForSEO `research_keywords` |
| Quick wins (paginas con potencial) | GSC `detect_quick_wins` |
| Dificultad de keywords | DataForSEO `get_keyword_difficulty` |
| Intencion de busqueda | DataForSEO `get_search_intent` |
| Keywords que posiciona competidor | DataForSEO `get_ranked_keywords` |
| Analisis de backlinks | DataForSEO Backlinks tools |
| Core Web Vitals | DataForSEO `get_page_lighthouse` o PageSpeed API |

---

## Changelog

### 2.1.0 (2026-02-05)
- **6 nuevas herramientas** (24 total) basadas en patrones del servidor oficial
- `get_domain_intersection`: Keywords compartidas entre dos dominios (analisis competitivo)
- `estimate_traffic`: Estimacion de trafico organico bulk para multiples dominios
- `get_keywords_for_site`: Keywords que un sitio targeta basado en contenido
- `get_historical_rank`: Ranking historico con distribucion de posiciones
- `get_keyword_ideas`: Ideas de keywords con intencion de busqueda
- `get_related_keywords`: Keywords semanticamente relacionadas

### 2.0.0 (2026-02-05)
- **13 nuevas herramientas** (18 total)
- DataForSEO Labs API: keyword difficulty, suggestions, search intent, ranked keywords, SERP competitors
- OnPage API: page SEO audit, Lighthouse/Core Web Vitals
- Advanced Backlinks: anchor texts, new/lost backlinks, referring domains
- Content Analysis: sentiment analysis
- Keywords Data: Google Trends
- Domain Analytics: technology detection
- Retry con exponential backoff para errores transitorios
- Excepciones personalizadas (QuotaExceededError, APINotAvailableError)
- Mensajes de error claros con instrucciones de activacion de API

### 1.1.0 (2026-02-05)
- Documentacion ampliada con ejemplos de respuesta

### 1.0.0 (2026-02-04)
- Version inicial con 5 herramientas basicas