# DataForSEO MCP Server

**Servidor MCP para keyword research y análisis SERP geolocalizado.**

Herramientas profesionales de investigación SEO/SEM que te permiten:
- 🔍 Descubrir keywords con volumen de búsqueda y métricas de dificultad
- 🌍 Análisis geolocalizado por país para mercados específicos
- 🏆 Identificar competidores dominantes en nichos temáticos
- 📊 Analizar SERPs y rankings de URLs con filtros avanzados
- 📈 Obtener tendencias históricas de keywords (Google Trends)
- 🎯 Research completo de dominios y páginas específicas

Powered by DataForSEO API.

## Requisitos

- Python 3.11+
- `pip` package manager
- Credenciales de DataForSEO API

## Instalación

1. **Navegar al directorio:**
   ```bash
   cd /Users/facundozupel/python_codigos/MCPs/mcp-dfs
   ```

2. **Crear archivo `.env` con tus credenciales:**
   ```bash
   cp .env.example .env
   # Editar .env con tus credenciales de DataForSEO
   ```

3. **Instalar dependencias:**
   ```bash
   pip install -r requirements.txt
   ```

## Ejecución del Servidor

El servidor usa **HTTP transport** con Server-Sent Events (SSE).

### Iniciar el servidor:
```bash
python mcp_dfs.py
```

El servidor se iniciará en `http://0.0.0.0:8000` por defecto.

Puedes personalizar el host y puerto en el archivo `.env`:
```bash
MCP_HOST=0.0.0.0
MCP_PORT=8000
```

### Verificar que el servidor está corriendo:
```bash
curl -I http://localhost:8000/mcp
```

Deberías ver una respuesta HTTP con status 405 (Method Not Allowed), lo cual es correcto.

## Configuración en Claude Desktop

Agregar al archivo de configuración de Claude Desktop:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "dataforseo": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

**Nota:** El servidor debe estar corriendo antes de iniciar Claude Desktop.

## Casos de Uso

### SEO
- Investigación de keywords para contenido y optimización on-page
- Análisis de competidores orgánicos en nichos específicos
- Identificación de oportunidades de ranking por país/región
- Auditorías de keywords posicionadas de dominios propios o competencia
- Análisis de tendencias estacionales para planificación de contenido

### SEM / Google Ads
- Descubrimiento de keywords para campañas pagas
- Análisis de volumen de búsqueda por geolocalización
- Identificación de keywords con bajo nivel de competencia
- Research de sitios para campañas de display/remarketing

### Análisis Competitivo
- Identificar qué dominios dominan espacios temáticos
- Reverse engineering de estrategias de keywords de competidores
- Análisis de SERPs para entender intención de búsqueda
- Evaluación de autoridad temática por nicho

## Herramientas Disponibles

### Investigación de Keywords

#### KeywordSuggestions
Obtiene sugerencias de keywords basadas en una keyword semilla.
- **Datos:** Volumen, dificultad, backlinks, domain rank
- **Uso:** Expansión de keywords, descubrimiento

#### KwsRelacionadas
Encuentra keywords semánticamente relacionadas.
- **Datos:** Keywords relacionadas con métricas
- **Uso:** Clustering temático, contenido relacionado

#### Tendencias
Analiza tendencias históricas de keywords (Google Trends).
- **Datos:** Series temporales mensuales
- **Uso:** Estacionalidad, análisis temporal

### Análisis de Competidores

#### TopicalAuthority
Identifica competidores dominantes en un espacio temático.
- **Datos:** Dominios, visibilidad, posiciones
- **Uso:** Análisis competitivo, identificación de autoridades

#### SerpCompetidores
Extrae competidores de SERP y sus keywords.
- **Datos:** URLs competidoras con keywords posicionadas
- **Uso:** Análisis SERP, reverse engineering

### Análisis de Rankings

#### RankedKeywordsGeneral
Obtiene keywords posicionadas para URLs específicas.
- **Datos:** Keywords, posiciones, métricas, filtros avanzados
- **Uso:** Auditoría SEO, análisis de rendimiento

#### Site
Keywords relacionadas a un sitio (Google Ads).
- **Datos:** Keywords de dominio/página
- **Uso:** Research de sitio completo

### Utilidades

#### Locaciones
Obtiene códigos de geolocalización para las herramientas.
- **Datos:** Mapeo país → código
- **Uso:** Helper para otras herramientas

## Ejemplos de Uso

### 1. Investigación de Keywords
```
Usuario: "Necesito keywords relacionadas con 'zapatos deportivos' en Argentina"

Claude usa:
1. Locaciones(pais="argentina") → código 2032
2. KeywordSuggestions(keyword="zapatos deportivos", locacion_codigo=2032)
3. KwsRelacionadas(keyword="zapatos deportivos", locacion_codigo=2032)
```

### 2. Análisis Competitivo
```
Usuario: "¿Quiénes dominan el espacio de 'marketing digital' en España?"

Claude usa:
1. Locaciones(pais="españa") → código 2724
2. TopicalAuthority(keywords=["marketing digital", "seo", "sem"], locacion_codigo=2724)
```

### 3. Auditoría de Sitio
```
Usuario: "Analiza para qué keywords rankea ejemplo.com"

Claude usa:
1. Locaciones(pais="...") → código
2. RankedKeywordsGeneral(url="ejemplo.com", locacion_codigo=codigo, filtro_posicion=20)
```

## Límites y Consideraciones

- **Rate Limiting:** DataForSEO tiene límites de requests/segundo según tu plan
- **Costos:** Cada llamada consume créditos de tu cuenta DataForSEO
- **Límites de resultados:**
  - KeywordSuggestions: máx 10,000 por consulta (default: 1,000)
  - Tendencias: máx 4 keywords por consulta (se procesan en lotes automáticamente)

## Troubleshooting

### Error: "Faltan las variables de entorno"
- Verifica que `.env` existe y contiene `DFS_USERNAME` y `DFS_PASSWORD`
- Reinicia Claude Desktop después de crear/modificar `.env`

### Error: "No se encontraron resultados"
- Verifica el `locacion_codigo` (usa herramienta Locaciones)
- Prueba con keywords más genéricas
- Revisa tu balance de créditos en DataForSEO

### Error de autenticación
- Verifica tus credenciales en https://app.dataforseo.com/api-access
- Asegúrate de usar email y API key (no password de cuenta)

### Error: "Connection refused" en Claude Desktop
- Verifica que el servidor MCP esté corriendo (`python mcp_dfs.py`)
- Verifica que el puerto 8000 esté libre: `lsof -i :8000`
- Revisa que la URL en claude_desktop_config.json sea `http://localhost:8000/mcp`

### Error: "Port already in use"
- Cambia el puerto en `.env`: `MCP_PORT=8001`
- O detén el proceso que está usando el puerto 8000

## Desarrollo

### Ejecutar localmente
```bash
python mcp_dfs.py
```

### Estructura del código
- **Sección 1-3:** Setup, environment, FastMCP
- **Sección 4:** KWResearch class (cliente API async)
- **Sección 5:** 8 herramientas MCP
- **Sección 6:** Main entrypoint (HTTP transport con uvicorn)

### Transport
El servidor utiliza **HTTP transport con SSE (Server-Sent Events)** en lugar de stdio. Esto permite:
- Mayor flexibilidad en el despliegue
- Separación del proceso del servidor y el cliente
- Posibilidad de múltiples clientes conectados simultáneamente
- Monitoreo y debugging más fácil

## Roadmap

### Fase 2 (Futuro)
- TopPages: Análisis de páginas top de dominios
- SiteLabs: Versión Labs de análisis de sitios
- TraficoEstimado: Estimación de tráfico orgánico
- KwsLive: Datos live de Google Ads

### Fase 3 (Futuro)
- SiteBulk: Procesamiento batch de múltiples dominios
- Funciones NLP: Modificadores, N-grams, Clustering OpenAI

## Licencia

Uso interno - DataForSEO API requiere suscripción comercial.

## Soporte

- DataForSEO Docs: https://docs.dataforseo.com/
- DataForSEO Support: https://dataforseo.com/contact