# grok-mcp

**Web 搜索 + X/Twitter 搜索** 的 MCP Server，供外部客户端（Claude Code / Cursor / Grok / OpenClaw / mcporter 等）调用。

HTTP 模式强制 **Bearer API Key** 鉴权。

> **给别人部署？** 看 [DEPLOY.md](./DEPLOY.md)（拷贝 / 安装 / 开机自启 / 客户端配置 / 安全清单）。

---

## 配置（`config.env`）

**端口和 Bearer Token 只写在配置文件里**，安装脚本直接读取。

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `GROK_MCP_API_KEY` | `gmk-web-x-2026` | **Bearer Token** |
| `GROK_MCP_PORT` | `17666` | 端口 |
| `GROK_MCP_HOST` | `0.0.0.0` | 监听地址 |
| `GROK_MCP_TRANSPORT` | `streamable-http` | 传输 |

### Bearer Token 用法（三选一）

```bash
# 1) 推荐：标准 Bearer
curl -sG 'http://127.0.0.1:17666/api/search' --data-urlencode 'q=MCP' \
  -H 'Authorization: Bearer gmk-web-x-2026'

# 2) X-API-Key
curl -sG 'http://127.0.0.1:17666/api/search' --data-urlencode 'q=MCP' \
  -H 'X-API-Key: gmk-web-x-2026'

# 3) 查询参数（方便浏览器/简单脚本）
curl -sG 'http://127.0.0.1:17666/api/search' \
  --data-urlencode 'q=MCP' --data-urlencode 'token=gmk-web-x-2026'
```

未带 Token 或 Token 错误 → **HTTP 401** + `WWW-Authenticate: Bearer`。  
`GET /health` 无需 Token。

改 Token/端口：编辑 `config.env` → `./install.sh` 或 `systemctl --user restart grok-mcp`。
---

## 目录结构

```
grok-mcp/
├── README.md / DEPLOY.md  # 说明
├── config.env             # ★ key / 端口 等（改这里）
├── .env.example           # 配置模板
├── install.sh             # ★ 一键安装入口
├── install-service.sh     # 安装实现
├── server.py / auth.py
├── grok-mcp.service.in    # systemd 模板
├── run.sh / run_stdio.sh
└── test_auth.sh
```

---

## 工具列表

| Tool | 说明 |
|------|------|
| `web_search` | 网页搜索（支持 `site:` 等） |
| `open_page` | 打开 URL，返回正文文本 |
| `news_search` | 新闻搜索 |
| `x_keyword_search` | X 关键词 / 高级语法搜索 |
| `x_user_search` | 搜用户 |
| `x_semantic_search` | 自然语言找相关帖 |
| `x_trending` | 当前热搜 |
| `x_status` | twitter CLI 登录状态 |

> 说明：这是 **等效能力** 封装，不是 Grok 内置索引的直出。X 完整帖搜索需可选配置 `TWITTER_AUTH_TOKEN` + `TWITTER_CT0`。

---

## 安装

```bash
cd /path/to/grok-mcp
# 可选：编辑 config.env（key / 端口，有默认值）
./install.sh
```

不改配置也能装：默认 key=`gmk-web-x-2026`，端口=`17666`。

完整部署说明见 **[DEPLOY.md](./DEPLOY.md)**。

---

## 启动

### 开机自启（推荐，重启后自动恢复）

已配置 **user systemd** 服务，机器重启后会自动拉起（`Linger=yes`）：

```bash
# 一键安装 / 启用 / 重启（读 config.env）
cd /path/to/grok-mcp
./install.sh

# 常用命令
systemctl --user status grok-mcp      # 状态
systemctl --user restart grok-mcp     # 重启服务
systemctl --user stop grok-mcp        # 停止
systemctl --user disable grok-mcp     # 取消开机自启
journalctl --user -u grok-mcp -f      # 看日志
curl -s http://127.0.0.1:17666/health # 健康检查
```

| 项 | 值 |
|----|-----|
| Unit 文件 | `~/.config/systemd/user/grok-mcp.service` |
| 副本 | `~/grok-mcp/grok-mcp.service` |
| 开机启用 | `enabled` → `default.target` |
| 崩溃恢复 | `Restart=always`（3s 后重试） |
| 配置加载 | `EnvironmentFile=.../config.env`（含 API Key） |

修改 `config.env` 后需：

```bash
systemctl --user restart grok-mcp
```

### HTTP 前台调试

```bash
cd /home/ubuntu/grok-mcp
./run.sh
# → http://0.0.0.0:17666/mcp
# 注意：若 systemd 已在跑，会端口冲突；先 systemctl --user stop grok-mcp
```

### stdio（本地 MCP 客户端拉起进程，不走 HTTP 鉴权）

```bash
./run_stdio.sh
```

### 鉴权自测

```bash
# 服务已由 systemd 运行时：
./test_auth.sh http://127.0.0.1:17666
```

期望：

- `GET /health` → 200
- `POST /mcp` **无** key → **401**
- `POST /mcp` **有** `Authorization: Bearer gmk-web-x-2026` → 非 401

---

## 直接 HTTP 搜索（REST，推荐脚本/业务调用）

服务已开简易 REST（需 Bearer，与 MCP 同一 key）：

```bash
BASE=http://127.0.0.1:17666
KEY=gmk-web-x-2026

# 网页搜索
curl -sG "$BASE/api/search" --data-urlencode 'q=OpenAI' --data-urlencode 'n=5' \
  -H "Authorization: Bearer $KEY"

# POST
curl -s -X POST "$BASE/api/search" \
  -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
  -d '{"q":"OpenAI","n":5}'

# 新闻 / 打开网页 / X 搜索 / 热搜
curl -sG "$BASE/api/news" --data-urlencode 'q=AI' -H "Authorization: Bearer $KEY"
curl -sG "$BASE/api/page" --data-urlencode 'url=https://example.com' -H "Authorization: Bearer $KEY"
curl -sG "$BASE/api/x/search" --data-urlencode 'q=Haaland' -H "Authorization: Bearer $KEY"
curl -s "$BASE/api/x/trending?region=worldwide" -H "Authorization: Bearer $KEY"
```

| 方法 | 路径 | 说明 |
|------|------|------|
| GET/POST | `/api/search?q=` | 网页搜索 |
| GET/POST | `/api/news?q=` | 新闻 |
| GET/POST | `/api/page?url=` | 抓取页面正文 |
| GET/POST | `/api/x/search?q=` | X 搜索 |
| GET | `/api/x/trending` | X 热搜 |
| GET | `/health` | 健康检查（无需 key） |
| POST | `/mcp` | 完整 MCP（给 AI 客户端） |

示例脚本：`examples/http-search.sh`

---

## 客户端配置

### 1) Grok — HTTP + Bearer

`~/.grok/config.toml`：

```toml
[mcp_servers.grok-mcp]
url = "http://127.0.0.1:17666/mcp"
headers = { Authorization = "Bearer gmk-web-x-2026" }
enabled = true
```

或 CLI：

```bash
grok mcp add --transport http grok-mcp http://127.0.0.1:17666/mcp \
  --header "Authorization: Bearer gmk-web-x-2026"
```

### 2) Grok — stdio（本机进程）

```toml
[mcp_servers.grok-mcp]
command = "python3"
args = ["/home/ubuntu/grok-mcp/server.py"]
env = { GROK_MCP_TRANSPORT = "stdio" }
enabled = true
```

```bash
grok mcp add grok-mcp --env GROK_MCP_TRANSPORT=stdio -- \
  python3 /home/ubuntu/grok-mcp/server.py
```

### 3) Claude Code / Cursor — `mcp.json`

**HTTP：**

```json
{
  "mcpServers": {
    "grok-mcp": {
      "url": "http://127.0.0.1:17666/mcp",
      "headers": {
        "Authorization": "Bearer gmk-web-x-2026"
      }
    }
  }
}
```

**stdio：**

```json
{
  "mcpServers": {
    "grok-mcp": {
      "command": "python3",
      "args": ["/home/ubuntu/grok-mcp/server.py"],
      "env": {
        "GROK_MCP_TRANSPORT": "stdio",
        "GROK_MCP_API_KEY": "gmk-web-x-2026"
      }
    }
  }
}
```

### 4) curl 示例

```bash
# 健康检查（无需 key）
curl -s http://127.0.0.1:17666/health

# 带鉴权访问 MCP 端点
curl -s http://127.0.0.1:17666/mcp \
  -H "Authorization: Bearer gmk-web-x-2026" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
```

### 5) mcporter

```json
{
  "mcpServers": {
    "grok-mcp": {
      "url": "http://127.0.0.1:17666/mcp",
      "headers": {
        "Authorization": "Bearer gmk-web-x-2026"
      }
    }
  }
}
```

```bash
mcporter list grok-mcp --schema
mcporter call grok-mcp.web_search query="MCP protocol" num_results=5
mcporter call grok-mcp.x_trending region=worldwide
```

---

## 环境变量

| 变量 | 默认 | 说明 |
|------|------|------|
| `GROK_MCP_API_KEY` | `gmk-web-x-2026` | HTTP Bearer key |
| `GROK_MCP_TRANSPORT` | `streamable-http` | `stdio` / `streamable-http` / `sse` |
| `GROK_MCP_HOST` | `0.0.0.0` | 监听地址 |
| `GROK_MCP_PORT` | `17666` | 监听端口 |
| `TWITTER_AUTH_TOKEN` | — | 可选，增强 X 搜索 |
| `TWITTER_CT0` | — | 可选，增强 X 搜索 |

---

## 安全说明

1. **生产环境务必更换** `GROK_MCP_API_KEY`，不要使用仓库示例值。
2. 公网暴露时建议再加反向代理（TLS + IP 限制）。
3. `config.env` 含密钥，**勿提交到公开仓库**（可只提交 `.env.example`）。
4. stdio 模式由本机客户端 spawn，一般不校验 HTTP Bearer；请控制谁能启动该进程。

---

## 能力边界

| 能力 | 说明 |
|------|------|
| Web 搜索 | DuckDuckGo 聚合，非 Grok 专有索引 |
| 打开网页 | httpx 抓取 + 简易去 HTML |
| X 热搜 | trends24 等公开站 |
| X 实时帖 | 有 cookie 时走 twitter-cli；否则 `site:x.com` 降级 |

---

## 故障排查

| 现象 | 处理 |
|------|------|
| HTTP 401 | 检查 `Authorization: Bearer …` 是否与 `config.env` 一致 |
| 连不上 | 确认 `./run.sh` 已启动，端口 `17666` |
| `web_search` 空结果 | 网络 / DDG 限流，稍后重试 |
| X 结果质量差 | 配置 `TWITTER_AUTH_TOKEN` + `TWITTER_CT0` |

```bash
# 查看 key 是否加载
python3 -c "from pathlib import Path; import os; exec(open('server.py').read().split('mcp =')[0]); print('key', API_KEY)"
# 或直接：
grep GROK_MCP_API_KEY config.env
```