Marketing Miner MCP Server

MCP server for the Marketing Miner Profilers API. Connects Claude, Cursor, Windsurf and other MCP clients to Marketing Miner keyword research and website analytics.

Available tools

Tool	Endpoint	Description
`marketing_miner_get_search_volume`	`GET /keywords/search-volume-data`	Search volume + CPC + YoY + seasonality for a single keyword
`marketing_miner_batch_search_volume`	`POST /keywords/search-volume-data`	Batch processing of 1–1000 keywords
`marketing_miner_get_keyword_suggestions`	`GET /keywords/suggestions`	Keyword suggestions (questions / new / trending) with difficulty and SERP features. Supports `limit` + `offset` with `has_more` / `next_offset` in the response.
`marketing_miner_get_website_stats`	`GET /websites/stats`	Estimated traffic, keyword count, breakdown by result_type
`marketing_miner_get_website_stats_range`	`GET/POST /websites/stats-range`	Historical traffic trend + competitor comparison

Every tool returns markdown (default, human-readable) or json (response_format: "json"), plus structuredContent with all API fields. Each tool declares an outputSchema for client-side validation.

Installation

Get an API token from marketingminer.com/en/features/api, then pick one of the options below.

Option A — Claude Code CLI one-liner (recommended, cross-platform)

Works on macOS, Windows and Linux — Claude Code CLI handles the config file location for you.

bash

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

-s user → installs globally (available from any project)
-e → sets the API token as environment variable
Replace YOUR_TOKEN with your actual Marketing Miner API token

To remove later: claude mcp remove marketing-miner -s user.

Option B — `npx` straight from GitHub (no clone needed)

The repo ships the built dist/ folder, so npx can run it directly.

Claude Desktop / Cursor / Windsurf config:

json

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

Option C — clone the repo (for development / customization)

bash

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

Then point your MCP client at the built binary:

json

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

Run locally with MARKETING_MINER_API_TOKEN=xxx npm start (stdio, default) or MCP_TRANSPORT=http MARKETING_MINER_API_TOKEN=xxx npm start (Streamable HTTP on port 8000).

Option D — Docker (self-hosted HTTP)

bash

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

Connect from a remote client via Streamable HTTP URL (see Connecting from an MCP client below).

Configuration

Variable	Default	Description
`MARKETING_MINER_API_TOKEN`	—	Required. API token from marketingminer.com/en/features/api
`MCP_TRANSPORT`	`stdio`	`stdio` (local MCP clients) or `http` (Streamable HTTP for hosted deployments)
`HOST`	`0.0.0.0`	HTTP bind host
`PORT`	`8000`	HTTP port
`MCP_HTTP_PATH`	`/mcp`	HTTP path

Alternative token names: MARKETING_MINER_API_KEY, MARKETING_MINER_TOKEN, MM_API_TOKEN, MM_API_KEY.

Remote HTTP client config

If you are running the server over Streamable HTTP (Option D above or any remote host), MCP clients connect via URL only:

json

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

Usage examples

1. Search volume for a single keyword:

"What is the search volume and seasonality of marketing in CZ?" → marketing_miner_get_search_volume({lang:"cs", keyword:"marketing"})

2. Batch processing:

"Compare search volume of SEO terms" → marketing_miner_batch_search_volume({lang:"cs", keywords:["seo","ppc","google ads","content marketing"]})

3. Question research for FAQ:

"Find questions around hypoteka" → marketing_miner_get_keyword_suggestions({lang:"cs", keyword:"hypoteka", suggestions_type:"questions", limit:50})

4. Paginating suggestions:

Fetch next page → marketing_miner_get_keyword_suggestions({lang:"cs", keyword:"hypoteka", limit:50, offset:50})

5. Competitor analysis:

"How much traffic does seznam.cz get?" → marketing_miner_get_website_stats({lang:"cs", type:"domain", target:"seznam.cz"})

6. Competitor trends:

"Compare traffic trends of seznam.cz vs. idnes.cz" → marketing_miner_get_website_stats_range({lang:"cs", type:"domain", target:"seznam.cz", period:"monthly", competitors:["idnes.cz"]})

Supported markets

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

Architecture

Node 18+, TypeScript (strict), ESM
MCP SDK ^1.18 (McpServer.registerTool, Zod input + output schemas, tool annotations)
Streamable HTTP (stateless per-request transport) + stdio
Zod runtime validation with .strict() (rejects unknown keys)
structuredContent + outputSchema on every tool
Response truncation for both markdown (25k chars) and oversized structuredContent arrays
Optional DNS-rebinding protection (Origin header validation when bound to loopback)