使用说明

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

Requisitos

Python 3.11+
pip package manager
Credenciales de DataForSEO API

Instalación

Navegar al directorio:

cd /Users/facundozupel/python_codigos/MCPs/mcp-dfs

Crear archivo .env con tus credenciales:

cp .env.example .env
# Editar .env con tus credenciales de DataForSEO

Instalar dependencias:
```
pip install -r requirements.txt
```

Ejecución del Servidor

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

Iniciar el servidor:

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:

MCP_HOST=0.0.0.0
MCP_PORT=8000

Verificar que el servidor está corriendo:

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

{
  "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

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