API Reference

API 参考

Grabby 提供 HTTP REST API、MCP 工具和 WebSocket 协议三套接口。

基础信息

基础 URL http://{HOST}:{PORT}
默认地址 http://localhost:5040
内容类型 application/json

认证

当后端配置了 API_KEY 时，所有请求需在 header 中携带 X-API-Key。API_KEY 留空时关闭认证。 

X-API-Key: your_api_key

POST /api/extract

提取指定 URL 的网页内容并返回 Markdown。

请求示例

curl -X POST http://localhost:5040/api/extract \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"url": "https://example.com"}'

请求参数

字段 类型 必填 说明
url string 是 要提取的网页 URL
browser string 否 指定浏览器名称（为空时使用默认浏览器）

成功响应 (200)

{
  "success": true,
  "url": "https://example.com",
  "title": "Example Domain",
  "markdown": "# Example Domain\n\nThis domain is for use..."
}

错误响应

503 Service Unavailable 
{"error": "Browser extension not connected"}
504 Gateway Timeout 
{"error": "Extract timeout or connection lost"}

GET /api/health

健康检查端点。

curl http://localhost:5040/api/health

"text-[#8b949e]"># 响应
{
  "status": "ok",
  "browser_connected": true,
  "timestamp": "2026-05-27T12: 00: 00Z"
}

GET /api/browsers

获取当前已连接的浏览器列表。

{
  "browsers": [
    {"conn_id": "ws_browser:browser-tools", "name": "chrome-home"},
    {"conn_id": "ws_browser:browser-tools", "name": "chrome-office"}
  ],
  "count": 2
}

POST /api/browsers/register

注册一个新的浏览器实例。浏览器在通过 WebSocket 连接之前需要先注册。

curl -X POST http://localhost:5040/api/browsers/register \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_api_key" \
  -d '{"connect_id": "browser-tools", "name": "chrome-office"}'

"text-[#8b949e]"># 响应
{
  "success": true,
  "browser": {
    "connect_id": "browser-tools",
    "name": "chrome-office"
  }
}

MCP 工具

MCP Server 挂载在 http://localhost:5040/mcp，使用 SSE 传输。可被 Claude Desktop、Cursor 等 AI Agent 直接调用。

tool: extract

提取指定网页的内容并返回 Markdown。

参数

参数 类型 必填 说明
url string 是 要提取的网页 URL
browser string 否 指定浏览器名称

返回

Markdown 格式的网页内容。

tool: screenshot

捕获指定网页的截图。

参数

参数 类型 必填 默认 说明
url string 是 — 要截图的网页 URL
fullPage boolean 否 false 是否截取整个页面

返回

Base64 编码的 PNG 图片数据。

其他工具

add(a, b) 计算两个数字的和，返回结果。
get_server_time() 获取服务器当前时间，返回 ISO 8601 格式时间字符串。

WebSocket 协议

连接端点

端点 用途
ws://{host}:{port}/ws_browser?conn_id={ID} 浏览器扩展连接
ws://{host}:{port}/ws_command?conn_id={ID} 命令客户端连接

消息格式

服务端发送给浏览器的请求消息：

{
  "source": "mcp_client",
  "action": "mcp_request",
  "command": "extract",
  "url": "https://example.com",
  "fullPage": false,
  "message_id": "msg-xxx"
}

浏览器返回的响应消息：

{
  "type": "response",
  "message_id": "msg-xxx",
  "command": "extract",
  "success": true,
  "result": {
    "url": "https://example.com",
    "title": "Example Domain",
    "content": {
      "content": "# Markdown content...",
      "wordCount": 42
    }
  }
}

错误码

HTTP 状态码

200请求成功
400请求参数错误
401API Key 校验失败
403connect_id 验证失败
502浏览器扩展执行错误
503浏览器扩展未连接
504请求超时

WebSocket 关闭码

1000正常关闭
1002API Key 校验失败
4001connect_id 验证失败