lukaskostka99-marketing-miner-mcp

Marketing Miner MCP 服务

面向 Marketing Miner Profilers API 的 MCP 服务。将 Claude、Cursor、Windsurf 和其他 MCP 客户端连接到 Marketing Miner 关键词研究和网站分析功能。

可用工具

工具	端点	描述
marketing_miner_get_search_volume	GET /keywords/search-volume-data	单个关键词的搜索量、CPC、同比数据和季节性
marketing_miner_batch_search_volume	POST /keywords/search-volume-data	批量处理 1–1000 个关键词
marketing_miner_get_keyword_suggestions	GET /keywords/suggestions	关键词建议（问题 / 新关键词 / 趋势关键词），包含难度和 SERP 功能。支持 limit 和 offset，响应中包含 has_more / next_offset。
marketing_miner_get_website_stats	GET /websites/stats	预估流量、关键词数量、按 result_type 分类的细分数据
marketing_miner_get_website_stats_range	GET/POST /websites/stats-range	历史流量趋势和竞争对手对比

每个工具都会返回 markdown（默认，方便阅读）或 json（response_format: "json"），以及包含所有 API 字段的 structuredContent。每个工具都声明了 outputSchema，供客户端验证。

安装

从 marketingminer.com/en/features/api 获取 API 令牌，然后选择以下选项之一。

选项 A — Claude Code CLI 单行命令（推荐，跨平台）

支持 macOS、Windows 和 Linux — Claude Code CLI 会为你处理配置文件位置。

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

• -s user → 全局安装（可用于任何项目）
• -e → 将 API 令牌设为环境变量
• 将 YOUR_TOKEN 替换为你的 Marketing Miner API 令牌

之后如需移除：claude mcp remove marketing-miner -s user。

选项 B — 直接通过 GitHub 使用 npx（无需克隆）

仓库自带已构建的 dist/ 文件夹，因此 npx 可以直接运行。

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

选项 C — 克隆仓库（用于开发 / 自定义）

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

然后将 MCP 客户端指向已构建的二进制文件：

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

使用 MARKETING_MINER_API_TOKEN=xxx npm start 在本地运行（stdio，默认），或使用 MCP_TRANSPORT=http MARKETING_MINER_API_TOKEN=xxx npm start 运行（在 8000 端口上使用 Streamable HTTP）。

选项 D — Docker（可自托管 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

通过 Streamable HTTP URL 从远程客户端连接（参见下文的 从 MCP 客户端连接）。

配置

变量	默认值	描述
MARKETING_MINER_API_TOKEN	—	必需。 从 marketingminer.com/en/features/api 获取的 API 令牌
MCP_TRANSPORT	stdio	stdio（本地 MCP 客户端）或 http（用于托管部署的 Streamable HTTP）
HOST	0.0.0.0	HTTP 绑定主机
PORT	8000	HTTP 端口
MCP_HTTP_PATH	/mcp	HTTP 路径

可用的替代令牌名称：MARKETING_MINER_API_KEY、MARKETING_MINER_TOKEN、MM_API_TOKEN、MM_API_KEY。

远程 HTTP 客户端配置

如果你通过 Streamable HTTP 运行此服务（上面的选项 D 或任何远程主机），MCP 客户端只需通过 URL 连接：

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

使用示例

1. 查询单个关键词的搜索量：

“marketing 在 CZ 的搜索量和季节性如何？” → marketing_miner_get_search_volume({lang:"cs", keyword:"marketing"})

2. 批量处理：

“比较 SEO 词条的搜索量” → marketing_miner_batch_search_volume({lang:"cs", keywords:["seo","ppc","google ads","content marketing"]})

3. 为常见问题研究问题：

“查找与 hypoteka 相关的问题” → marketing_miner_get_keyword_suggestions({lang:"cs", keyword:"hypoteka", suggestions_type:"questions", limit:50})

4. 对建议进行分页：

获取下一页 → marketing_miner_get_keyword_suggestions({lang:"cs", keyword:"hypoteka", limit:50, offset:50})

5. 竞争对手分析：

“seznam.cz 的流量有多少？” → marketing_miner_get_website_stats({lang:"cs", type:"domain", target:"seznam.cz"})

6. 竞争对手趋势：

“比较 seznam.cz 与 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（严格模式）、ESM
• MCP SDK ^1.18（McpServer.registerTool、Zod 输入和输出架构、工具注解）
• Streamable HTTP（每个请求使用无状态传输）+ stdio
• 使用 .strict() 进行 Zod 运行时验证（拒绝未知键）
• 每个工具均包含 structuredContent + outputSchema
• 对 Markdown（25k 字符）和超大 structuredContent 数组进行响应截断
• 可选的 DNS 重绑定保护（绑定到环回地址时验证 Origin 标头）

许可证

MIT