lukaskostka99 marketing miner mcp

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:

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

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