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.
Herramienta | Endpoint | Descripción |
|
| Volumen de búsqueda + CPC + YoY + estacionalidad para una sola palabra clave |
|
| Procesamiento por lotes de 1 a 1000 palabras clave |
|
| Sugerencias de palabras clave (preguntas / nuevas / en tendencia) con dificultad y características de SERP. Admite |
|
| Tráfico estimado, recuento de palabras clave, desglose por result_type |
|
| Tendencia histórica de tráfico + comparación con competidores |
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.
Related MCP server: SurfRank MCP Server
Obtén un token de API en marketingminer.com/en/features/api y luego elige una de las siguientes opciones.
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.
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"
}
}
}
}git clone https://github.com/lukaskostka/marketing-miner-mcp.git
cd marketing-miner-mcp
npm install
npm run buildLuego 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).
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-mcpConéctate desde un cliente remoto a través de la URL HTTP Streamable (consulta Conexión desde un cliente MCP a continuación).
Variable | Predeterminado | Descripción |
| — | Obligatorio. Token de API de marketingminer.com/en/features/api |
|
|
|
|
| Host de enlace HTTP |
|
| Puerto HTTP |
|
| Ruta HTTP |
Nombres de token alternativos: MARKETING_MINER_API_KEY, MARKETING_MINER_TOKEN, MM_API_TOKEN, MM_API_KEY.
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"
}
}
}1. Volumen de búsqueda para una sola palabra clave:
"¿Cuál es el volumen de búsqueda y la estacionalidad de
marketingen 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"]})
cs, sk, pl, hu, ro, gb, us
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)
MIT
Fetch volume, CPC, YoY change and 12-month seasonality for up to 1000 keywords in one POST request.
Args:
lang: Market code (cs/sk/pl/hu/ro/gb/us).
keywords: 1-1000 keywords (each 2-80 chars).
response_format: 'markdown' (default) or 'json'.
Returns an array of records, one per keyword. Prefer this over calling marketing_miner_get_search_volume in a loop - it is one API credit per keyword and much faster.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | Yes | Language/market code. 'gb' = United Kingdom, 'us' = United States. | |
| keywords | Yes | 1-1000 keywords. Each 2-80 chars. | |
| response_format | No | Output format. 'markdown' for human reading, 'json' for structured processing. | markdown |
| Name | Required | Description |
|---|---|---|
| lang | Yes | |
| count | Yes | |
| keywords | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark readOnly and idempotent. The description adds that it is a POST request (non-modifying query), returns an array of records, and mentions API credit cost and speed, which are useful beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three brief paragraphs with clear sections: purpose, args, and return/guidance. No unnecessary words; efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple inputs, existence of output schema, and annotations covering safety, the description fully addresses purpose, parameters, output, and usage guidance. No obvious gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all parameters. The description restates most constraints but adds context like response format options and market code examples, adding marginal value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches volume, CPC, YoY change, and seasonality for up to 1000 keywords via POST. It distinguishes from the sibling 'marketing_miner_get_search_volume' by explicitly recommending batch over looping.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises to use this tool over calling the singular version in a loop, citing cost and speed. Provides key usage constraints (up to 1000 keywords, 2-80 chars, market codes) and formats.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve related keyword suggestions with optional full metrics (difficulty, SERP features, volume, CPC, seasonality).
Args:
lang: Market code (cs/sk/pl/hu/ro/gb/us).
keyword: Seed keyword (2-80 chars).
suggestions_type (optional): 'questions' | 'new' | 'trending'. Omit for a general mix.
with_keyword_data (default true): include search_volume, cpc, difficulty, serp_features, yoy_change, peak_month, monthly_sv.
limit (default 50, max 1000): client-side window size.
offset (default 0): client-side offset into API results for pagination.
response_format: 'markdown' or 'json'.
Returns: keywords[limit], plus total_available, has_more, next_offset for pagination.
Use for topical research, content-cluster ideation, FAQ mining (suggestions_type='questions'), trend discovery (suggestions_type='trending').
| Name | Required | Description | Default |
|---|---|---|---|
| lang | Yes | Language/market code. 'gb' = United Kingdom, 'us' = United States. | |
| keyword | Yes | Keyword to analyze (2-80 chars). | |
| suggestions_type | No | Filter suggestions: 'questions' (question-style), 'new' (newly appearing), 'trending' (gaining traffic). | |
| with_keyword_data | No | Include difficulty, SERP features and volume metrics for each suggestion. | |
| limit | No | Maximum suggestions to return (client-side window over API payload). | |
| offset | No | Client-side offset into the full API response. Use with limit to paginate. | |
| response_format | No | Output format. 'markdown' for human reading, 'json' for structured processing. | markdown |
| Name | Required | Description |
|---|---|---|
| lang | Yes | |
| seed_keyword | Yes | |
| suggestions_type | Yes | |
| total_available | Yes | |
| returned | Yes | |
| offset | Yes | |
| has_more | Yes | |
| next_offset | Yes | |
| export_credits_cost | Yes | |
| keywords | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds significant behavioral context beyond the annotations: it explains pagination (limit/offset), the effect of with_keyword_data, return fields (total_available, has_more, next_offset), and the 'Omit for a general mix' for suggestions_type. No contradiction with annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concisely structured with a main sentence followed by bullet points for arguments and return. Every sentence adds value; no extraneous words. The purpose is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (7 params, 2 required), high schema coverage, and presence of annotations and output description, the description is complete. It covers input semantics, output structure, and pagination, leaving no major gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but the description adds crucial semantics beyond the schema: it clarifies 'client-side window size' for limit, 'client-side offset into API results' for offset, the default behavior of with_keyword_data, and what 'Omit' means for suggestions_type. This provides valuable insight for proper invocation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's verb ('Retrieve'), resource ('related keyword suggestions'), and optional metrics. It explicitly lists specific use cases (topical research, FAQ mining, trend discovery) that distinguish it from sibling tools focused on search volume and website stats.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases for the tool (e.g., 'Use for topical research, content-cluster ideation, FAQ mining'). While it does not explicitly state when not to use or name alternatives, the context signals (sibling tools) and the clear use cases give adequate guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch monthly search volume, CPC, year-over-year change, peak month and full 12-month seasonality for a single keyword.
Args:
lang: Market code (cs/sk/pl/hu/ro/gb/us).
keyword: Keyword to analyze (2-80 chars).
response_format: 'markdown' (default) or 'json'.
Returns a single record with: keyword, search_volume, cpc{value, currency_code}, yoy_change, peak_month, monthly_sv (12 months).
Use when you need volume/CPC/seasonality for ONE keyword. For multiple keywords, use marketing_miner_batch_search_volume.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | Yes | Language/market code. 'gb' = United Kingdom, 'us' = United States. | |
| keyword | Yes | Keyword to analyze (2-80 chars). | |
| response_format | No | Output format. 'markdown' for human reading, 'json' for structured processing. | markdown |
| Name | Required | Description |
|---|---|---|
| keyword | Yes | |
| search_volume | Yes | |
| cpc | Yes | |
| yoy_change | Yes | |
| peak_month | Yes | |
| monthly_sv | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, idempotentHint, openWorldHint. The description adds details on return fields and output format, which is useful but does not contradict annotations. It could mention rate limits or auth, but not required given read-only nature.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: three sentences covering purpose, arguments, return structure, and usage guidance. No fluff, front-loaded with the main action.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 3 parameters with schema coverage 100% and an output schema exists. The description covers all necessary information: what it does, parameters, return fields, and when to use it versus siblings. It is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with well-described parameters. The description adds value by explaining the purpose of response_format (human reading vs structured processing) and listing market codes explicitly. It also clarifies keyword length constraints, though schema already has them.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches monthly search volume, CPC, year-over-year change, peak month, and seasonality for a single keyword. It uses a specific verb ('Fetch') and resource ('search volume' for a keyword), and distinguishes from the sibling batch tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use when you need volume/CPC/seasonality for ONE keyword. For multiple keywords, use marketing_miner_batch_search_volume.' This provides clear when-to-use and when-not-to-use guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Aggregate organic/paid traffic, keyword counts and result-type breakdown for a domain, subdomain, prefix, or exact URL.
Args:
lang: Market code (cs/sk/pl/hu/ro/gb/us).
type: 'domain' | 'subdomain' | 'prefix' | 'exact'.
target: Target value (3-253 chars). Examples: 'seznam.cz', 'blog.seznam.cz', 'https://seznam.cz/email/'.
scheme (optional, for type='exact' or 'prefix'): 'https' | 'http'.
response_format: 'markdown' or 'json'.
Returns: stats[] per result_type (organic, paid, ai_overviews, local_pack, images, videos, ...), plus totals (estimated_traffic_sum, number_of_keywords_sum).
Use for competitor sizing, SEO audits, and SERP-feature distribution analysis.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | Yes | Language/market code. 'gb' = United Kingdom, 'us' = United States. | |
| type | Yes | Target granularity: 'domain' (example.com), 'subdomain' (blog.example.com), 'prefix' (URL prefix), 'exact' (exact URL). | |
| target | Yes | Target value (domain, subdomain, or URL, 3-253 chars). | |
| scheme | No | URL scheme. Only relevant for type='exact' or 'prefix'. | |
| response_format | No | Output format. 'markdown' for human reading, 'json' for structured processing. | markdown |
| Name | Required | Description |
|---|---|---|
| stats | Yes | |
| estimated_traffic_sum | Yes | |
| estimated_traffic_change_sum | Yes | |
| number_of_keywords_sum | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, idempotentHint=true. The description adds context on the output structure: 'stats[] per result_type (organic, paid, ai_overviews, ...) plus totals.' This goes beyond the annotations, providing useful behavioral insight. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise (four sentences) with front-loaded summary. It uses a clean 'Args' block for parameter details. Every sentence earns its place, no redundancy. Structured format aids quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description adequately explains the return values (stats per result type plus totals). All parameters are explained with examples. The tool's complexity is moderate, and the description covers all necessary information for an agent to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all 5 parameters with descriptions (100% coverage). The description adds value by providing concrete examples for 'target' (e.g., 'seznam.cz') and clarifies the usage of 'scheme' parameter. This enhances understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it aggregates organic/paid traffic, keyword counts, and result-type breakdown for various URL granularities. It explicitly names the resource ('website stats') and the verb ('aggregate'). Sibling tools like batch search volume and keyword suggestions are distinct, so no confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases: 'competitor sizing, SEO audits, and SERP-feature distribution analysis.' This gives clear context on when to use the tool. However, it does not explicitly state when not to use it or mention alternatives, but the use cases are sufficient for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Historical traffic time series (daily/weekly/monthly) for a target, with optional competitor comparison.
Args:
lang: Market code.
type: 'domain' | 'subdomain' | 'prefix' | 'exact'.
target: 3-253 chars.
scheme (optional): 'https' | 'http'.
period (optional): 'daily' | 'weekly' | 'monthly'.
competitors (optional, max 10): list of competitor domains/URLs.
response_format: 'markdown' or 'json'.
Returns: stats_range[] (date, result_type, estimated_traffic) + optional competitors[] with their own stats_range. Use for trend analysis, year-over-year charts, and competitor benchmarking.
| Name | Required | Description | Default |
|---|---|---|---|
| lang | Yes | Language/market code. 'gb' = United Kingdom, 'us' = United States. | |
| type | Yes | Target granularity: domain / subdomain / prefix / exact. | |
| target | Yes | Target value (3-253 chars). | |
| scheme | No | ||
| period | No | Aggregation period for the time series. | |
| competitors | No | Up to 10 competitor domains/URLs. Each competitor uses the same 'type' as the primary target (e.g. if type='domain', pass bare domains). | |
| response_format | No | Output format. 'markdown' for human reading, 'json' for structured processing. | markdown |
| Name | Required | Description |
|---|---|---|
| stats_range | Yes | |
| competitors | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, destructiveHint, and openWorldHint. The description adds behavioral details beyond these, such as the output structure (stats_range[] with date, result_type, estimated_traffic, and optional competitors), the maximum of 10 competitors, and the response format options. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with clear sections for Args and Returns. It is front-loaded with the core purpose and every sentence is necessary. No fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, optional output schema), the description is complete. It explains the purpose, each parameter's role (with additional context for competitors), the return structure, and typical use cases. The presence of an output schema reduces the need to detail return values, but the description still provides a useful summary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is high (86%), but the description adds meaningful context: it clarifies that competitors use the same 'type' as the primary target, and it explains the output structure. The schema already documents most parameters well, so the description provides incremental value without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it provides 'Historical traffic time series (daily/weekly/monthly) for a target, with optional competitor comparison.' It uses a specific verb ('get') and resource ('time range'), differentiating it from sibling tools like 'get_website_stats' (likely single-point) and others.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states 'Use for trend analysis, year-over-year charts, and competitor benchmarking.' While it doesn't explicitly state when not to use this tool, the context implies it's for time-range data, distinguishing it from single-point alternatives. No explicit alternative tools are named, but the sibling list is available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v3.2.0marketing_miner_batch_search_volumemarketing_miner_get_keyword_suggestionsmarketing_miner_get_search_volumemarketing_miner_get_website_statsmarketing_miner_get_website_stats_rangeScored across 5 tools
Each tool targets a distinct operation: single vs. batch search volume, keyword suggestions, website stats snapshot vs. historical range. No functional overlap exists.
All tools follow a consistent 'marketing_miner_<action>_<resource>' pattern (e.g., marketing_miner_batch_search_volume, marketing_miner_get_keyword_suggestions). No mixed conventions.
5 tools is well-scoped for a focused SEO data retrieval server, covering keyword research and website analysis without unnecessary bloat.
Covers core workflows: keyword volume (single and batch), suggestions with metrics, website stats (snapshot and historical). Minor gap: no standalone keyword difficulty tool, but difficulty is included in suggestions with_keyword_data.
Real SEO data for AI assistants: page audits, Keyword Planner volumes, Search Console history.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
SEO research, audits, backlinks, GSC, and content workflow tools for AI agents.
AI-powered SEO and marketing: keyword research, SERP analysis, and content optimization tools.
