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

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

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