# Grok Web MCP

一个仅供个人研究和自用的 Grok 网页 MCP Server。架构对齐 `webgpt2mcp`：使用持久化 Camoufox 浏览器操作 Grok 网页，再通过 OpenAI 兼容网关提供给本地或远程 MCP，提供：

- `grok_web_search`：强制网页搜索，返回回答和结构化来源
- `grok_chat`：普通对话
- `grok_continue`：在同一 Grok 会话中继续对话
- `grok_status`：本地会话与配置状态
- `grok_accounts`：列出多账号 Profile 和运行状态

> 这是非官方的网页端自动化方案。请只使用自己的账号，控制调用频率，并自行确认 xAI 的服务条款。登录资料只保存在本机 `accounts/`。

## 直接连接已部署服务

如果你已经拿到部署方发给你的 Bearer Token，不需要在本机安装 Python、Camoufox 或本项目，直接在 Codex 配置远程 MCP：

```toml
[mcp_servers.grok-web-remote]
url = "https://grok.sciaccept.top/mcp"
bearer_token_env_var = "GROK_WEB_MCP_TOKEN"
tool_timeout_sec = 300
startup_timeout_sec = 30
```

启动 Codex 前设置：

```bash
export GROK_WEB_MCP_TOKEN="部署方发给你的 token"
```

可用工具：

- `grok_chat`：让 Grok 网页账号回答普通问题
- `grok_web_search`：让 Grok 使用网页搜索
- `grok_continue`：继续上一轮 Grok 网页会话
- `grok_status`：检查指定账号状态
- `grok_accounts`：列出服务器上的 Grok 账号状态

如果服务端配置了多账号，可以在工具参数里传 `account_id`，例如 `work`、`team1`。同一个 Bearer Token 当前可以访问该服务器上的所有已配置账号，请只发给可信用户。

```text
Codex / Claude / Cursor
  → Grok MCP（stdio）
  → MCP 自动管理的本地 OpenAI 兼容网关（127.0.0.1:3000）
  → 后台无界面的持久化 Camoufox / Playwright 浏览器
  → 已登录的 grok.com 网页
```

## 安装

从 GitHub 拉取并安装：

```bash
git clone https://github.com/zijueming/Grok-Web-MCP.git
cd Grok-Web-MCP
```

```bash
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m camoufox fetch
cp .env.example .env
```

## 首次网页登录

运行登录模式会打开一个专用、可见的 Camoufox 浏览器：

```bash
.venv/bin/grok-web-mcp login --id default
```

请在这个浏览器中登录 Grok，并确认可以正常发送消息。完成后回终端按 Enter；浏览器 Profile 会保存到 `accounts/default/camoufox-profile/`，以后启动网关会自动复用。

多账号时，为每个账号使用不同 `--id`：

```bash
.venv/bin/grok-web-mcp login --id work
.venv/bin/grok-web-mcp login --id team1
.venv/bin/grok-web-mcp accounts
```

每个账号独立保存到 `accounts/<account_id>/camoufox-profile/`。`account_id` 只允许字母、数字、下划线、点和短横线。

如果需要固定代理节点，在 `.env` 设置：

```bash
GROK_CAMOUFOX_PROXY=http://127.0.0.1:7890
```

## 运行 MCP

```bash
.venv/bin/grok-web-mcp
```

不需要先启动浏览器或网关。MCP 会自动在后台启动无界面的 Camoufox，复用已保存的登录 Profile；MCP 退出时，它启动的后台进程也会自动关闭。如果本机已经有可用网关，则直接复用且不会将其关闭。

在 Claude Desktop、Cursor 等 stdio MCP 客户端中配置：

```json
{
  "mcpServers": {
    "grok-web": {
      "command": "/绝对路径/Grok4.5API/.venv/bin/grok-web-mcp",
      "cwd": "/绝对路径/Grok4.5API"
    }
  }
}
```

只有首次登录或登录失效时，才需要手动运行 `login`，届时会显示浏览器窗口供你登录。正常 MCP 调用不会显示 Camoufox。

## 可选：单独启动 OpenAI 兼容网关

如果还要让其他 OpenAI 兼容客户端直接调用，可以单独启动：

```bash
.venv/bin/grok-web-mcp gateway
```

它会提供：

- `GET /health`
- `GET /accounts`
- `GET /v1/models`
- `POST /v1/chat/completions`

接口鉴权由 `.env` 中的 `GROK_GATEWAY_API_KEY` 控制。默认只监听 `127.0.0.1`。OpenAI 兼容调用可在请求 JSON 里传 `account_id`：

```json
{
  "model": "grok-web",
  "messages": [{"role": "user", "content": "hello"}],
  "account_id": "work"
}
```

## 可选：Grok CLI OAuth 模式

如你有 Grok Build/CLI 权限，可在 `.env` 设置 `GROK_AUTH_MODE=oauth`，然后运行：

```bash
.venv/bin/grok-web-mcp oauth-login --id default
```

Grok 网页 DOM 升级时，主要调整 `src/grok_web_mcp/browser_backend.py` 中的输入框、发送按钮和回答选择器，无需抓取或保存网页 API Cookie。

`chrome-extension/` 是早期 Bridge 实验实现，当前默认路径不需要安装 Chrome 插件。

## 服务器模式（Streamable HTTP）

服务器模式适合自托管：一个部署实例可以管理多个 Grok 网页账号 Profile。它提供：

- `POST /mcp`：远程 MCP Streamable HTTP
- `GET /healthz`：不含敏感信息的存活检查
- Bearer Token 鉴权
- 后台自动启动 OpenAI 兼容网关和无界面 Camoufox
- Linux/Docker Profile 持久化
- `grok_accounts` / `grok_status(account_id=...)`：账号状态检查
- `grok_chat(account_id=...)` / `grok_web_search(account_id=...)`：指定账号调用

不要把内部的 `3000` 网关端口直接暴露到公网。当前版本是“多 Grok 账号管理”，不是完整多租户权限系统：持有同一个 MCP Bearer Token 的客户端可以指定任意已配置的 `account_id`。给不互信用户开放前，应增加 token 到账号的绑定、限流和审计。

### 直接运行

先生成令牌并配置环境变量：

```bash
export GROK_REMOTE_API_KEY="$(openssl rand -hex 32)"
export GROK_REMOTE_PUBLIC_URL="http://127.0.0.1:8000"
export GROK_REMOTE_HOST="127.0.0.1"
export GROK_REMOTE_PORT="8000"
.venv/bin/grok-web-mcp remote
```

验证：

```bash
curl http://127.0.0.1:8000/healthz
```

公网使用必须放在 Caddy、Nginx、Traefik 或云负载均衡之后提供 HTTPS。`deploy/Caddyfile.example` 提供了最小 Caddy 示例。

### Docker Compose

```bash
cp .env.server.example .env.server
openssl rand -hex 32
# 将结果分别填入 GROK_REMOTE_API_KEY 和 GROK_GATEWAY_API_KEY
mkdir -p server-data/accounts/default
docker compose build
docker compose up -d
docker compose ps
```

首次网页登录建议先在有图形界面的电脑运行：

```bash
.venv/bin/grok-web-mcp login --id default
.venv/bin/grok-web-mcp login --id work
```

登录成功后，将整个账号目录下的 `camoufox-profile/` 安全复制到服务器。例如：

```text
server-data/accounts/default/camoufox-profile/
server-data/accounts/work/camoufox-profile/
```

Profile 含有登录凭据，不要提交 Git，不要通过公共网盘分发。服务器与本机系统差异导致登录态不可复用时，应在带桌面环境的同系统 Linux 主机完成一次登录，再复制 Profile。

### Codex 连接远程 MCP

在运行 Codex 的电脑设置令牌环境变量：

```bash
export GROK_WEB_MCP_TOKEN="服务器上的 GROK_REMOTE_API_KEY"
```

在 `~/.codex/config.toml` 添加：

```toml
[mcp_servers.grok-web-remote]
url = "https://grok.sciaccept.top/mcp"
bearer_token_env_var = "GROK_WEB_MCP_TOKEN"
tool_timeout_sec = 300
startup_timeout_sec = 30
```

自托管时将 URL 换成自己的域名，例如 `https://grok.example.com/mcp`。保存后重启 Codex。远程服务器不需要在每台客户端安装 Python、Camoufox 或本项目。

调用时可以让客户端自然选择默认账号，也可以明确指定：

```text
用 Grok 的 work 账号搜索今天 xAI 的最新消息
```

MCP 工具层等价于传入 `account_id="work"`。

## 返回结构与长任务

用户看到的仍是完整回答；MCP 额外返回 `provider`、`request_type`、`completed`、`elapsed_seconds`、`conversation_id`、来源数量和是否自动续跑等结构化字段。来源 URL 来自 Grok 网页，默认标记为 `unverified`，调用方仍应核验关键来源。

默认等待 240 秒。若 Grok 明确显示请求中断，服务会在同一会话自动发送一次继续指令。