内容
# 间谍Fu MCP
一个模型上下文协议服务器，暴露了 [SpyFu](https://www.spyfu.com/api) 的PPC情报API，使其可作为工具从Claude Code、Cursor和其他支持MCP的客户端中使用。
十种工具涵盖了域名统计、广告历史、顶级PPC竞争对手、付费SERP、组合（共享关键词分析）、相关关键词、付费关键词导出、有机关键词和历史排名。
## 安装
需要Python 3.11+。
```bash
git clone <此仓库> spyfu-mcp
cd spyfu-mcp
python3 -m venv .venv
./.venv/bin/pip install -e ".[dev]"
```
这会在 `./.venv/bin/spyfu-mcp` 处创建一个控制台脚本。
**macOS / iCloud Drive 注意：** Python 3.14 跳过标记有 macOS `UF_HIDDEN` 标志的 `.pth` 文件，而 iCloud Drive 将此标志应用于 `~/Library/Mobile Documents/` 中的文件。如果您在 iCloud Drive 中克隆了此仓库，并且安装后 `import spyfu_mcp` 失败，请将虚拟环境放在 iCloud 外部：
```bash
python3 -m venv ~/.local/share/spyfu-mcp/venv
~/.local/share/spyfu-mcp/venv/bin/pip install -e ".[dev]"
```
## 配置
从 [SpyFu API 控制台](https://www.spyfu.com/api) 获取API密钥。
复制 `.env.example`，如果您想在 `.env` 文件中保留您的密钥用于开发；在生产环境中，密钥通过MCP服务器的 `env` 块传递（见下文）。
| 变量 | 必需 | 默认值 | 用途 |
|---|---|---|---|
| `SPYFU_API_KEY` | 是 | — | 您的 SpyFu API 密钥。服务器在没有它的情况下拒绝启动。 |
| `SPYFU_COUNTRY_CODE` | 否 | `US` | 所有调用的默认国家/地区代码。可以通过 `country_code` 工具参数重写。 |
## 连接到 Claude Code
添加到您项目的 `.mcp.json`（或全局的 `~/.claude/settings.json`）：
```json
{
"mcpServers": {
"spyfu": {
"command": "/绝对路径/to/.venv/bin/spyfu-mcp",
"env": {
"SPYFU_API_KEY": "您的密钥",
"SPYFU_COUNTRY_CODE": "US"
}
}
}
}
```
重启 Claude Code。10个 `spyfu_*` 工具变得可用。通过 `/mcp` 验证。
## 连接到 Cursor
相同的配置模式。添加到 `~/.cursor/mcp.json`（全局）或 `.cursor/mcp.json`（按项目）：
```json
{
"mcpServers": {
"spyfu": {
"command": "/绝对路径/to/.venv/bin/spyfu-mcp",
"env": { "SPYFU_API_KEY": "您的密钥" }
}
}
}
```
## 工具
| 工具 | 参数 | 返回值 |
|---|---|---|
| `spyfu_domain_stats` | `domain` | 终身每月统计数据（预算、点击量、关键词、平均广告排名） |
| `spyfu_domain_stats_for_date` | `domain`, `month`, `year` | 特定月份的统计数据 |
| `spyfu_ad_history` | `domain` | 历史广告创意（标题、正文、位置、关键词） |
| `spyfu_top_ppc_competitors` | `domain` | 按关键词重叠排名的顶级PPC竞争对手 |
| `spyfu_paid_serps` | `query` | 每个域名都在竞标关键词，附带广告文案 + 位置 |
| `spyfu_domain_paid_keywords` | `domain` | 域名的完整付费关键词列表 |
| `spyfu_kombat` | `domains: list[str]` (2+) | 多个域名竞争的关键词 |
| `spyfu_related_keywords` | `query` | 相关的关键词，包含流量、每次点击成本、付费竞争对手 |
| `spyfu_most_valuable_keywords` | `domain` | 按估计流量价值排名的顶级有机关键词 |
| `spyfu_historic_rankings` | `domain` | 历史有机SERP排名变化 |
所有工具都接受可选的 `country_code`（覆盖该调用的env默认值），并且大多数工具接受 `starting_row` / `page_size` 进行分页。
## 示例提示
参见 [`examples/usage.md`](examples/usage.md) 以获取自然语言提示，这些提示会调用每个工具。
## 开发
```bash
./.venv/bin/pytest # 离线测试（24个测试，~7秒）
SPYFU_LIVE=1 ./.venv/bin/pytest tests/test_smoke.py # 调用真实API
```
离线测试套件涵盖了每个端点的URL/参数构造、环境处理、结构化HTTP错误、速率限制底线以及通过进程内FastMCP客户端进行端到端MCP工具注册和调度。
## 速率限制和成本
客户端强制执行请求之间的0.5秒间隔。SpyFu自己的API配额按调用消耗 — 在进行高容量拉取之前，请检查您的计划限制。
## 许可证
MIT。
