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.

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)

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)

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:

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

License

MIT

marketing-miner-mcp