内容
# zyte-mcp
> **免责声明：** 本项目并非 Zyte 官方产品，而是由社区独立开发的 MCP 服务器。API、工具行为和配置可能会在未通知的情况下发生变化。
专注于任务的 MCP 服务器，用于 Zyte API 和 Scrapy Cloud，设计用于与 AI 编程助手（如 Claude）一起使用。
## 要求
- Python 3.13+
- `ZYTE_API_KEY` — 所有 Zyte API 工具所需的密钥
- `SCRAPY_CLOUD_API_KEY`（或 `SHUB_APIKEY`）— 仅 Scrapy Cloud 工具所需的密钥
## 安装
```bash
uv sync --extra dev
```
## 运行
```bash
ZYTE_API_KEY=您的密钥 uv run zyte-mcp
```
服务器通过 `stdio` 进行通信。
要启用 Scrapy Cloud 工具：
```bash
ZYTE_API_KEY=您的密钥 SCRAPY_CLOUD_API_KEY=您的-scrapy-cloud-密钥 uv run zyte-mcp
```
`SHUB_APIKEY` 被接受为 `SCRAPY_CLOUD_API_KEY` 的别名。
## Claude 桌面版
macOS 上的 Claude 桌面版从以下位置读取 MCP 服务器配置：
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
最小配置（仅限 Zyte API 工具）：
```json
{
"mcpServers": {
"zyte": {
"command": "uv",
"args": [
"run",
"--directory",
"/绝对路径/to/zyte-mcp",
"zyte-mcp"
],
"env": {
"ZYTE_API_KEY": "您的-zyte-api-密钥"
}
}
}
}
```
在 `env` 块中添加 `SCRAPY_CLOUD_API_KEY` 以启用 Scrapy Cloud 工具。
如果 Claude 桌面版无法找到 `uv`，请将 `"uv"` 替换为 `which uv` 返回的绝对路径，然后完全重启 Claude 桌面版。
## 工具
### Zyte API — HTTP
**`fetch_http`**
使用 Zyte HTTP 模式（无浏览器渲染）获取 URL。
- 在可能的情况下返回解码文本；原始正文可作为 `body_base64` 获取
- 支持自定义标头、cookie、POST 正文、地理位置和住宅 IP
- 用于静态 HTML、JSON API、站点地图和任何不需要 JavaScript 的页面
**`render_page`**
使用 Zyte 的真实浏览器渲染页面。
- 返回 JavaScript 执行后的完整浏览器 HTML
- 支持浏览器操作：`click`、`type`、`scroll_bottom`、`scroll_to`、`wait_for_selector`、`wait_for_timeout`、`select`、`hover`、`key_press`、`evaluate`
- 可以通过 `include_iframes` 包含 iframe 内容
- 当页面需要 JavaScript 或用户交互才能显示内容时使用
**`screenshot_page`**
使用 Zyte 浏览器模式捕获页面的截图。
- 返回 JPEG 或 PNG 图片
- 支持 `full_page` 捕获和与 `render_page` 相同的浏览器操作集
- 用于视觉验证页面或调试渲染问题
### Zyte API — 搜索
**`search`**
使用 Zyte 的搜索 API（`POST /v1/search`）进行搜索。
- `query` — 搜索关键词
- `domain` — 搜索引擎域名（默认为 `google.com`）
- `max_results` — 要返回的有机结果数量；必须是 10 到 100 之间（默认为 `10`）的 10 的倍数
- `include_organic` — 返回解析的有机结果，包含 `rank`、`title`、`url`、`snippet`、`displayed_url`（默认为 `true`）
- `include_html` — 返回原始的 SERP HTML；可以与 `include_ai_overview` 结合使用，无需额外付费 API 费用
- `include_ai_overview` — 触发完整浏览器渲染，并解析 Google 的 AI 概述为结构化 `{ text, sources[] }`（当查询可用时）（默认为 `false`）
- `query_parameters` — 可选的地理定位和本地化控制：
- 通用（可移植）：`geolocation`（例如 `"US"`）、`locale`（例如 `"en-US"`）
- 引擎特定（Google）：`gl`、`hl`、`cr`、`lr`、`safe`、`nfpr`、`uule` — 样式自动从已设置的字段中检测
### Zyte API — 提取
所有提取工具都调用 Zyte 的 AI 驱动的自动提取。它们共享一组共同的选项：`extract_from`、`geolocation`、`ip_type`、`session_id`、`request_cookies`、`response_cookies` 和 `custom_attributes`。
**`extract_product`**
从产品详情页中提取结构化产品数据（名称、价格、SKU、图片、描述、可用性等）。
**`extract_product_list`**
从类别或搜索结果页面中提取产品摘要列表。
**`extract_article`**
从新闻或博客页面中提取结构化文章数据（标题、正文、作者、日期等）。
**`extract_page_content`**
从任何页面中提取主要可读内容，当更具体的类型不适用时。
### Scrapy Cloud — 部署
**`scrapy_cloud_deploy`**
将本地 Scrapy 项目部署到 Scrapy Cloud。
- 需要 `shub` 可用；通过 `uv add shub` 在项目内或通过 `pip install shub` 在全局安装
- 当项目目录中存在 `.venv` 时，自动通过 `uv run shub` 调用 `shub`
- 在部署前运行预检查：
- 验证 `shub` 可调用
- 验证 `scrapy.cfg` 存在于 `project_path`
- 验证目标项目已知（存在 `scrapinghub.yml`，或提供 `project_id`）
- 当提供 `project_id` 且尚不存在 `scrapinghub.yml` 时，工具自动创建两个文件：
- **`requirements.txt`** — 从 `pyproject.toml` 中的 `[project].dependencies` 构建，排除 `scrapy` 本身（云栈提供）
- **`scrapinghub.yml`** — 具有项目 ID、正确的 Scrapy 栈版本（`stack: scrapy:X.Y`）和指向 `requirements.txt` 的指针的最小配置
- 失败时，任何在输出中检测到的 scrapy 版本不匹配都作为 `scrapy_version_hint` 显示
- 返回 `success`、`project_id`、`version`、`stdout`、`stderr`
### Scrapy Cloud — 作业
**`scrapy_cloud_run_spider`**
在 Scrapy Cloud 上启动蜘蛛作业。接受 `project_id`、`spider` 名称、选项 `job_args`、`job_settings`、`priority`、`units` 和 `add_tag`。
**`scrapy_cloud_list_jobs`**
列出项目的作业。按 `spider`、`state`（`pending`、`running`、`finished`）、`has_tag`、`lacks_tag` 和 `count` 过滤。
**`scrapy_cloud_cancel_job`**
取消正在运行或等待的作业。接受 `job_key`，格式为 `project_id/spider_id/job_id`。
**`scrapy_cloud_update_job_tags`**
添加或删除作业的标签。传递标签字符串列表到 `add` 和/或 `remove`。
**`scrapy_cloud_count_jobs`**
统计项目的待处理或正在运行的作业， optionally 按蜘蛛名称或标签过滤。
**`scrapy_cloud_get_activity`**
获取项目的最近活动事件（部署、作业状态更改等）。
**`scrapy_cloud_list_spiders`**
列出部署到 Scrapy Cloud 项目的所有蜘蛛。
### Scrapy Cloud — 作业数据
**`scrapy_cloud_get_job_metadata`**
返回作业的所有元数据字段（蜘蛛名称、状态、时间戳、项目数量、错误数量等）。
**`scrapy_cloud_get_job_metadata_field`**
返回作业的单个命名元数据字段。当只需要一个值时，比获取所有元数据更高效。
**`scrapy_cloud_list_items`**
从已完成的作业中返回抓取的项目。支持 `start` 偏移和 `count` 限制用于分页。
**`scrapy_cloud_get_logs`**
返回作业的日志条目。支持 `count` 以限制返回的行数。
**`scrapy_cloud_list_requests`**
返回作业期间记录的 HTTP 请求记录。支持 `start` 和 `count` 用于分页。
## 进行中
**`infer_product_schema`** — 一个工具，通过一个或多个产品页面 URL（通过 Zyte API 获取，使用 Claude 提取字段，并生成 `@attrs.define` 类 + JSON 架构）推断出类型化的产品数据架构，存在于代码库中，但尚未暴露给工具用户。该工具在进一步测试和完善之前处于禁用状态。
## 注意事项
- `ip_type="residential"` 可能成本更高，需要 Zyte KYC 批准
- 地理位置选择可能会影响成本和成功率
- `session_id` 由客户端管理；此服务器不会创建或持久化会话
- `custom_attributes` 需要标准提取类型，不支持 `serp`
- 浏览器工具仅支持 `referer` 作为初始请求标头
- Scrapy Cloud 使用与 Zyte API 不同的 API 密钥
- Scrapy Cloud 变更操作故意限制为运行作业、取消作业和更新标签
## 测试
```bash
uv run pytest
```
