Servidor MCP de Marketing Miner

Servidor MCP para la API de Profilers de Marketing Miner. Conecta Claude, Cursor, Windsurf y otros clientes MCP a la investigación de palabras clave y analítica de sitios web de Marketing Miner.

Herramientas disponibles

Cada herramienta devuelve markdown (predeterminado, legible por humanos) o json (response_format: "json"), además de structuredContent con todos los campos de la API. Cada herramienta declara un outputSchema para la validación del lado del cliente.

Instalación

Obtén un token de API en marketingminer.com/en/features/api y luego elige una de las siguientes opciones.

Opción A — Comando de una línea para Claude Code CLI (recomendado, multiplataforma)

Funciona en macOS, Windows y Linux: Claude Code CLI gestiona la ubicación del archivo de configuración por ti.

claude mcp add marketing-miner \
  -s user \
  -e MARKETING_MINER_API_TOKEN=YOUR_TOKEN \
  -- npx -y github:lukaskostka/marketing-miner-mcp

• -s user → instala globalmente (disponible desde cualquier proyecto)

• -e → establece el token de API como variable de entorno

• Reemplaza YOUR_TOKEN con tu token real de la API de Marketing Miner

Para eliminarlo más tarde: claude mcp remove marketing-miner -s user.

Opción B — npx directamente desde GitHub (no requiere clonar)

El repositorio incluye la carpeta dist/ compilada, por lo que npx puede ejecutarlo directamente.

Configuración de Claude Desktop / Cursor / Windsurf:

{
  "mcpServers": {
    "marketing-miner": {
      "command": "npx",
      "args": ["-y", "github:lukaskostka/marketing-miner-mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "MARKETING_MINER_API_TOKEN": "your_token_here"
      }
    }
  }
}

Opción C — clonar el repositorio (para desarrollo / personalización)

git clone https://github.com/lukaskostka/marketing-miner-mcp.git
cd marketing-miner-mcp
npm install
npm run build

Luego apunta tu cliente MCP al binario compilado:

{
  "mcpServers": {
    "marketing-miner": {
      "command": "node",
      "args": ["/absolute/path/to/marketing-miner-mcp/dist/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "MARKETING_MINER_API_TOKEN": "your_token_here"
      }
    }
  }
}

Ejecuta localmente con MARKETING_MINER_API_TOKEN=xxx npm start (stdio, predeterminado) o MCP_TRANSPORT=http MARKETING_MINER_API_TOKEN=xxx npm start (HTTP Streamable en el puerto 8000).

Opción D — Docker (HTTP autohospedado)

git clone https://github.com/lukaskostka/marketing-miner-mcp.git
cd marketing-miner-mcp
docker build -t marketing-miner-mcp .
docker run -p 8000:8000 -e MARKETING_MINER_API_TOKEN=your_token_here marketing-miner-mcp

Conéctate desde un cliente remoto a través de la URL HTTP Streamable (consulta Conexión desde un cliente MCP a continuación).

Configuración

Nombres de token alternativos: MARKETING_MINER_API_KEY, MARKETING_MINER_TOKEN, MM_API_TOKEN, MM_API_KEY.

Configuración del cliente HTTP remoto

Si estás ejecutando el servidor a través de HTTP Streamable (Opción D anterior o cualquier host remoto), los clientes MCP se conectan solo mediante URL:

{
  "mcpServers": {
    "marketing-miner": {
      "url": "https://your-host.example.com/mcp"
    }
  }
}

Ejemplos de uso

1. Volumen de búsqueda para una sola palabra clave:

"¿Cuál es el volumen de búsqueda y la estacionalidad de marketing en CZ?" → marketing_miner_get_search_volume({lang:"cs", keyword:"marketing"})

2. Procesamiento por lotes:

"Compara el volumen de búsqueda de términos SEO" → marketing_miner_batch_search_volume({lang:"cs", keywords:["seo","ppc","google ads","content marketing"]})

3. Investigación de preguntas para FAQ:

"Encuentra preguntas sobre hypoteka" → marketing_miner_get_keyword_suggestions({lang:"cs", keyword:"hypoteka", suggestions_type:"questions", limit:50})

4. Paginación de sugerencias:

Obtener la siguiente página → marketing_miner_get_keyword_suggestions({lang:"cs", keyword:"hypoteka", limit:50, offset:50})

5. Análisis de la competencia:

"¿Cuánto tráfico recibe seznam.cz?" → marketing_miner_get_website_stats({lang:"cs", type:"domain", target:"seznam.cz"})

6. Tendencias de la competencia:

"Compara las tendencias de tráfico de seznam.cz vs. idnes.cz" → marketing_miner_get_website_stats_range({lang:"cs", type:"domain", target:"seznam.cz", period:"monthly", competitors:["idnes.cz"]})

Mercados admitidos

cs, sk, pl, hu, ro, gb, us

Arquitectura

• Node 18+, TypeScript (estricto), ESM

• MCP SDK ^1.18 (McpServer.registerTool, esquemas de entrada y salida Zod, anotaciones de herramientas)

• HTTP Streamable (transporte sin estado por solicitud) + stdio

• Validación en tiempo de ejecución Zod con .strict() (rechaza claves desconocidas)

• structuredContent + outputSchema en cada herramienta

• Truncamiento de respuesta tanto para markdown (25k caracteres) como para arrays de structuredContent demasiado grandes

• Protección opcional contra rebinding de DNS (validación del encabezado Origin cuando está vinculado a loopback)

Licencia

MIT