TinyFish

@tiny-fish/mcp

TinyFish MCP 服务：为 Claude、Cursor、VS Code 和任何 MCP 客户端提供网页搜索、页面抓取与提取、浏览器自动化和页面监控。Search 和 Fetch 免费。

在浏览器或桌面应用中使用 Claude 或 ChatGPT？ 无需进行设置，只需一键添加适用于 Claude 或 ChatGPT 的官方 TinyFish 插件。它集成了这些工具，以及现成的技能和安全规则。

此软件包是一个透明的反向代理，会在本地公开一个 Streamable-HTTP MCP 端点 http://127.0.0.1:3711/mcp，并将每个请求转发到托管的 TinyFish MCP 服务 https://agent.tinyfish.ai/mcp。

此代理不定义任何自己的工具或架构。tools/list、tools/call、resources/*、错误，以及 run_web_automation SSE 进度流都来自托管服务：流式（SSE）响应会逐字节转发，非流式 JSON 响应则会以内容相同的方式转发（解析并重新序列化，与上游内容深度相等）。托管服务返回的内容，就是客户端看到的内容。

工具

托管服务提供 28 种工具。你可以使用它们搜索网页、抓取并提取页面内容、自动化操作浏览器、运行远程 Chrome 会话（CDP）、保留已登录状态的 Browser Context Profiles，以及安排页面和主题监控。

类别	工具
搜索与抓取	search、fetch_content
网页自动化	run_web_automation、run_web_automation_async、get_run、list_runs、cancel_run、batch_status、batch_cancel
浏览器会话	create_browser_session、list_browser_sessions、close_browser_session
Browser Context Profiles	create_profile、list_profiles、start_profile_setup_session、save_profile_setup_session、cancel_profile_setup_session
监控	create_monitor、get_monitor、list_monitors、run_monitor、pause_monitor、resume_monitor、cancel_monitor
账户与用量	get_wallet、get_search_usage、list_fetch_usage、guide_next_step

• 工具参考：逐字列出每种工具及其参数
• 示例：常见工作流和提示词
• MCP 集成指南：客户端设置、身份验证、频率限制和故障排查
• 完整文档：docs.tinyfish.ai

优先使用托管服务

如果你的 MCP 客户端支持远程 Streamable-HTTP 服务（Claude Code、 Claude Desktop connectors、Cursor、VS Code 和大多数现代客户端都支持）， 请直接连接到托管服务——无需安装，也无需本地进程：

https://agent.tinyfish.ai/mcp

在以下情况下使用此软件包：

• 你的客户端只能连接到本地 MCP 服务，或
• 你希望使用环境中的 TinyFish API 密钥进行身份验证，而不是使用托管服务的 OAuth 流程（适用于 CI、无头机器和脚本）。

安装

npm install -g @tiny-fish/mcp

或者无需安装即可运行：

npx @tiny-fish/mcp

需要 Node.js >= 22。（这是有意区别于 TinyFish CLI 的 >=24 要求——这里没有任何内容需要 Node 24。）

API 密钥

服务启动时会从环境中读取 TINYFISH_API_KEY，并在每次调用时将其作为 X-API-Key 发送到上游。请前往 https://agent.tinyfish.ai 获取密钥。

export TINYFISH_API_KEY=tf_...
tinyfish-mcp

成功后，它会向 stderr 输出一行内容：

tinyfish-mcp [info] listening on http://127.0.0.1:3711 — upstream https://agent.tinyfish.ai/mcp — v0.1.0

密钥绝不会被记录，也绝不会回传给客户端。

客户端配置

启动 tinyfish-mcp（例如在终端中，或使用你选择的进程管理器），然后将客户端指向 http://127.0.0.1:3711/mcp。

Claude Code

claude mcp add --transport http tinyfish http://127.0.0.1:3711/mcp

Claude Desktop

前往 Settings → Connectors → Add custom connector，并使用 URL http://127.0.0.1:3711/mcp。对于支持基于 URL 的服务的 claude_desktop_config.json 版本：

{
  "mcpServers": {
    "tinyfish": {
      "url": "http://127.0.0.1:3711/mcp"
    }
  }
}

注意：Claude Desktop 也可以直接将托管的 https://agent.tinyfish.ai/mcp 用作自定义连接器；除非需要使用 API 密钥进行身份验证，否则建议优先使用此方式。

Cursor

~/.cursor/mcp.json（或项目中的 .cursor/mcp.json）：

{
  "mcpServers": {
    "tinyfish": {
      "url": "http://127.0.0.1:3711/mcp"
    }
  }
}

VS Code

.vscode/mcp.json：

{
  "servers": {
    "tinyfish": {
      "type": "http",
      "url": "http://127.0.0.1:3711/mcp"
    }
  }
}

其他客户端

配置一个 Streamable-HTTP（远程/URL）MCP 服务：

{ "url": "http://127.0.0.1:3711/mcp" }

端点仅接受 POST /mcp（与托管服务一致；该服务没有 GET SSE 通道，也不支持 DELETE 会话拆除）。GET /healthz 会返回 200 ok，供调试使用。

环境变量

变量	默认值	描述
TINYFISH_API_KEY	（必填）	TinyFish API 密钥，会作为 X-API-Key 发送给上游。未设置此密钥时，服务会拒绝启动。
PORT	3711	本地监听端口（整数，范围为 1-65535）。不会自动递增：如果端口已被占用，服务会报错并退出。
TINYFISH_UPSTREAM_URL	https://agent.tinyfish.ai/mcp	上游 MCP URL。必须使用 https:；仅在 127.0.0.1/localhost 上允许使用 http:（用于本地测试）。

代理还会在每次上游调用时发送归属标头： X-TF-Request-Origin: tinyfish-mcp、X-TF-Client-Name: tinyfish-mcp 和 X-TF-Client-Version: <package version>。

安全与信任模型

这是一个仅限环回连接的服务，并设有明确记录的信任边界：

• 始终绑定环回地址。 服务绑定到 127.0.0.1 字面地址，且不可配置——它绝不会监听 0.0.0.0 或局域网接口。
• 来源验证。 对于带有 Origin 标头的请求，除非来源为 http(s)://127.0.0.1 或 http(s)://localhost（任意端口），否则会以 403 拒绝。这可阻止 MCP 规范针对本地 HTTP 服务所指出的 DNS 重绑定攻击。不带 Origin 标头的请求（curl、MCP SDK、检查器）则允许通过。
• 密钥由服务持有。 进程会从其环境中读取 TINYFISH_API_KEY； 客户端在本地链路上无需发送凭据。这是最简单的模式，但这意味着任何能够访问 127.0.0.1:<port> 的本地进程都可以使用你的密钥并驱动自动化操作（这可能会消耗 TinyFish 额度）。环回绑定和 Origin 检查是缓解措施；请将该端口视为可信机器上的本地信任边界。

故障排除

“端口 3711 已被占用”——另一个进程正在占用该端口。请停止该进程，或将 PORT 设为可用端口，并相应更新客户端配置。

HTTP 502，JSON-RPC 错误 -32001（“上游拒绝了请求…… 请检查 TINYFISH_API_KEY 是否设置为有效的 TinyFish API 密钥”）——托管服务拒绝了你的密钥。请确认 TINYFISH_API_KEY 已设置在 tinyfish-mcp 进程的环境中（而不仅仅是你的 shell），并确认该密钥在 https://agent.tinyfish.ai 上有效。错误的 data 字段包含上游状态和（截断后的）响应正文，可用于诊断。

HTTP 502，JSON-RPC 错误 -32000（“无法连接……”）——无法访问上游服务：请检查网络、代理和 VPN；托管服务也可能暂时不可用。如果你覆盖了 TINYFISH_UPSTREAM_URL，请检查该值。如果流式 run_web_automation 调用在流传输过程中失败，你会在最终 SSE 帧中收到相同的 -32000，并附带“运行可能仍在执行”的警告，以及已知时的 runId——请检查运行状态，而不要盲目重试。

批量请求无法使用——MCP 不允许 JSON-RPC 批处理，托管服务也不支持批量数组。代理会原样转发批量请求，上游会返回自身的错误；请每个请求发送一条 JSON-RPC 消息。

Claude/其他客户端无法连接——请确保 tinyfish-mcp 确实正在运行（它是独立服务；客户端不会启动它），并确认 GET http://127.0.0.1:3711/healthz 返回 ok。

开发

npm ci
npm run build        # tsc → dist/, marks dist/index.js executable
npm test             # unit tests (offline, mock upstream)
npm run test:watch   # unit tests in watch mode
npm run lint         # eslint over src/ tests/
npm run format       # prettier
npm run type-check   # tsc --noEmit over the whole tree

布局：src/core/ 是与传输方式无关的代理核心（上游客户端、会话桥接、SSE 中继、错误整形）；src/http/ 是轻量级 HTTP 适配器（路由、Origin 检查）；tests/ 包含单元测试套件，以及 tests/helpers/mock-upstream.ts，这是托管端点的模拟实现，单元测试完全离线运行。

集成测试会调用真实的托管上游服务，并且受条件限制：如果没有 TINYFISH_API_KEY，测试会跳过并打印提示。

TINYFISH_API_KEY=... npm run test:integration

设置 TINYFISH_UPSTREAM_URL，即可让测试指向沙盒部署，而非生产环境。请注意，run_web_automation 集成测试会执行真实自动化任务并消耗额度。

维护

由 @Zechereh 维护。错误报告和功能请求：GitHub issues。

许可证

MIT