# MCP 服务

Model Context Protocol（MCP）让 LLM 驱动的代理（Claude Desktop、Cursor、Cline 等）调用外部工具。helodata 提供 MCP 服务器，把带代理的 fetch + ISP/会话管理作为工具直接暴露给 agent。

## 服务器提供的工具

| 工具                    | 描述                                                 |
| --------------------- | -------------------------------------------------- |
| `helo_fetch`          | 通过 helodata 抓取 URL，可选产品（`res`/`mob`/`isp`）、地区、粘性会话 |
| `helo_list_locations` | 返回 `res`、`mob` 可用的国家/城市/ASN                        |
| `helo_isp_list`       | 返回你购买的 ISP IP                                      |
| `helo_traffic_today`  | 当日按产品和子账号的带宽用量                                     |

## 安装

```bash
npm i -g @helodata/mcp-server
```

或用 `npx` 直接运行：

```bash
npx -y @helodata/mcp-server --api-key=YOUR_HELODATA_API_KEY
```

## 在 Claude Desktop 配置

编辑 `claude_desktop_config.json`（Settings → Developer → Edit Config）：

```json
{
  "mcpServers": {
    "helodata": {
      "command": "npx",
      "args": ["-y", "@helodata/mcp-server"],
      "env": {
        "HELODATA_API_KEY":      "YOUR_API_KEY",
        "HELODATA_SUBUSER":      "s1a2b3c4d5e",
        "HELODATA_SUBUSER_PASS": "PASSWORD"
      }
    }
  }
}
```

重启 Claude Desktop，新工具会出现在工具列表中。

## 在 Cursor / Cline 配置

同样的 JSON，键名为 `mcp`（Cursor）或 `mcp_servers`（Cline）。具体字段名见各工具文档。

## Agent 提示示例

> "用 `helo_fetch` 工具从一个德国住宅 IP 获取 `https://example.de` 的首页，并总结 meta description。"

Agent 自动选 `helo_fetch`，参数 `region=de`、`type=res`，获取页面、解析、总结。

## MCP 中的粘性会话

`helo_fetch` 接受 `session_id` 参数。同一对话中多次调用传相同值即可复用出口 IP——多步流程很有用。

## 安全提示

MCP 服务器用你的 API 密钥计费与认证，**把它当数据库密码对待**。Agent 不需要管订单/子账号时，把 API 密钥范围收紧到只读。

## 常见陷阱

* **MCP 服务器不出现** — 查 Claude Desktop 日志：macOS `~/Library/Logs/Claude/mcp.log`。多数为 Node 版本不匹配（需要 Node 18+）。
* **`helo_fetch` 返回 407** — 配置里的环境变量凭证错，请在控制台核对。
* **大响应** — `helo_fetch` 默认在 1 MB 后截断。需要完整 HTML 时，agent 调用时传 `max_bytes` 参数提升上限。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.helodata.com/helodata-zh/ji-cheng-zhi-nan/ai-yu-gong-zuo-liu/mcp.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.