grok-mcp

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

HTTP 模式强制 Bearer API Key 鉴权。

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

---

配置（config.env）

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

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

# 客户端 Header
Authorization: Bearer gmk-web-x-2026
# 或: X-API-Key: gmk-web-x-2026

# MCP:  http://127.0.0.1:17666/mcp
# 健康: GET /health（无需鉴权）

改 key/端口：编辑 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。

---

安装

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

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

完整部署说明见 DEPLOY.md。

---

启动

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

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

# 一键安装 / 启用 / 重启（读 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 后需：

systemctl --user restart grok-mcp

HTTP 前台调试

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

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

./run_stdio.sh

鉴权自测

# 服务已由 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）：

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：

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

或 CLI：

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

2) Grok — stdio（本机进程）

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

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

3) Claude Code / Cursor — mcp.json

HTTP：

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

stdio：

{
  "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 示例

# 健康检查（无需 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

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

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

# 查看 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