hotlogin-mcp

HotLogin Local API 的 MCP（Model Context Protocol）服务封装，用于让 AI Agent / MCP 客户端通过标准 MCP tools 调用本地 HotLogin 服务，实现：

环境（Env）生命周期管理：创建、查询、更新、删除、启动、关闭、窗口整理等
分组（Group）管理：创建、查询、更新、删除
代理（Proxy）管理：创建、查询、更新、删除
浏览器自动化（Pilot）：连接已启动环境的 CDP WebSocket，进行页面访问、截图、元素交互、Cookie/Storage 读写等

提示：本项目只负责“调用本地 HotLogin 服务”，不包含 HotLogin 客户端本身。

功能概览

核心管理能力（Local API）

health_check
env_*：env_query / env_profile / env_create / env_revise / env_launch / env_terminate / env_terminate_all / env_opened / env_window_layout …
group_*：group_query / group_create / group_revise / group_remove
proxy_*：proxy_query / proxy_create / proxy_revise / proxy_remove

自动化能力（Pilot）

会话：session_attach / tab_spawn
页面：page_visit / page_capture / page_text / page_html / page_meta / page_reload / page_back / page_forward / page_wait_load
元素：element_tap / element_write / element_pick / element_hover / element_scroll / element_move / element_wait / element_exists / element_text / element_attr / element_count / element_check / element_uncheck / element_frame_tap
输入与脚本：key_press / script_eval / mouse_click_pos / dialog_handle
状态：cookie_read / cookie_write / cookie_clear / storage_read / storage_write

工具的完整注册列表见 src/mcp/tools.ts，参数校验见 src/mcp/schemas.ts。

前置条件

已安装并启动 HotLogin 客户端，确保本地 Local API 可用
Node.js >= 18

安装与构建

在本仓库目录下：

npm install
npm run build

构建产物默认在 build/，可执行入口为 build/server.core.js（见 package.json 的 main/bin）。

在 MCP 客户端中使用

Cursor / Claude Desktop（stdio）

将 MCP Server 配置加入你的客户端配置中（示例为 npx 运行已发布包；若你本地开发，可改成 node <path>/build/server.core.js）。

macOS / Linux

{
  "mcpServers": {
    "hotlogin-local-api": {
      "command": "npx",
      "args": ["-y", "hotlogin-local-api-mcp"]
    }
  }
}

Windows

{
  "mcpServers": {
    "hotlogin-local-api": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "hotlogin-local-api-mcp"]
    }
  }
}

如果你还没发布到 npm：把 command/args 改为 node 直接指向本地构建产物即可。

配置（环境变量）

该 MCP server 会请求 HotLogin Local API。常用配置如下（具体字段见 src/api/config.ts）：

LOCAL_SERVICE_ENDPOINT：本地服务地址（例如 http://127.0.0.1:50325 之类）
LOCAL_SERVICE_PORT：本地服务端口（当 endpoint 未设置时使用）
LOCAL_SERVICE_TOKEN：鉴权 token（如你的本地服务启用了鉴权）

在 MCP 客户端的 server 配置里可以通过 env 传入，例如：

{
  "mcpServers": {
    "hotlogin-local-api": {
      "command": "npx",
      "args": ["-y", "hotlogin-local-api-mcp"],
      "env": {
        "LOCAL_SERVICE_PORT": "50325",
        "LOCAL_SERVICE_TOKEN": "your-token"
      }
    }
  }
}

常见问题

health_check 失败

确认 HotLogin 客户端已启动
确认 LOCAL_SERVICE_ENDPOINT/PORT 指向正确
如启用鉴权，确认 LOCAL_SERVICE_TOKEN 正确

session_attach 失败或超时

wsEndpoint 可能已经过期：重新 env_launch 获取新的 endpoint
确认本机到该 ws 地址可达（防火墙/端口占用等）

安全提示

请妥善保管 LOCAL_SERVICE_TOKEN，不要提交到仓库或分享给不可信方
自动化工具会直接驱动浏览器执行操作，请在可信环境中使用并设置合理的超时与资源清理流程

License

如需开源发布，请在此处补充你的项目许可证文件（例如 LICENSE）。

hotlogin-mcp

hotlogin-mcp

功能概览

核心管理能力（Local API）

自动化能力（Pilot）

前置条件

安装与构建

在 MCP 客户端中使用

Cursor / Claude Desktop（stdio）

macOS / Linux

Windows

配置（环境变量）

推荐工作流（典型用法）

创建环境并进行自动化

常见问题

health_check 失败

session_attach 失败或超时

安全提示

License

Reviews