内容
<div align="center">
<img src="assets/hero.svg" alt="UniGrok · Grok MCP Server & Gateway — one Grok server, every IDE, zero pasted API keys" width="100%"/>
[](https://github.com/djtelicloud/grok-mcp-server/actions)
[](https://github.com/djtelicloud/grok-mcp-server/releases)
[](pyproject.toml)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://docs.x.ai/?utm_source=github&utm_medium=readme&utm_campaign=unigrok&utm_content=badge-docs)
[快速开始](#快速开始) · [IDE 设置](#ide-设置) · [工具界面](#工具界面) · [架构](#架构) · [安全模型](#安全模型)
</div>
# UniGrok · Grok MCP 服务器与网关
UniGrok 是一个本地优先的 **Grok MCP 服务器与网关**，适用于 [xAI 的 Grok 模型](https://docs.x.ai/?utm_source=github&utm_medium=readme&utm_campaign=unigrok&utm_content=intro-docs)。它在您的机器上运行一次，将 xAI 凭证保留在服务器端，并让 Claude Desktop、Claude Code、VS Code、Codex、Antigravity 等 MCP 客户端共享同一个 Grok 代理，通过 Streamable HTTP 路由，具有双平面路由跨 xAI API 和 Grok CLI 订阅，按次调用成本跟踪和浏览器控制中心。
当前版本：**v0.4.1**。
使用方式：
- 一个共享的多 IDE Grok MCP 服务器，地址为 `http://localhost:8080/mcp`。
- 一个适用于 `unigrok-agent` 的 OpenAI 兼容本地网关。
- 一个具有网络搜索、X 搜索、代码执行、文件、图像/视频生成、会话内存、遥测和反射的结构化代理托管。
## 快速开始
```bash
git clone https://github.com/djtelicloud/grok-mcp-server.git
cd grok-mcp-server
uv run python main.py init
```
初始化命令：
- 复制 `example.env` 到 `.env`，当 `.env` 不存在时。
- 如果 `.env` 已经存在，则不修改。
- 打印 VS Code、Claude Desktop、Claude Code 和 Codex 的复制粘贴配置。
- 将每个 IDE 指向共享的 HTTP 端点，而不是要求每个 IDE 提供原始 xAI 密钥。
编辑 `.env` 并设置您的密钥 — 如果您还没有，可以从 [xAI 控制台](https://console.x.ai/?utm_source=github&utm_medium=readme&utm_campaign=unigrok&utm_content=quickstart-get-key) 获取一个：
```bash
XAI_API_KEY=your_real_xai_api_key
```
然后启动共享服务：
```bash
docker compose up --build -d
curl -s http://localhost:8080/healthz
```
打开本地控制中心：
```text
http://localhost:8080/ui/
```
*控制中心的快速测试控制台 — 每个 `agent` 调用都报告令牌、成本（美元）、延迟、路由和平面，实时显示原始 JSON-RPC 线路日志。*
## 安装脚本
用于引导本地启动：
```bash
./install.sh
```
检查 `uv`、`git` 和 Docker，同步 Python 环境，运行 `init`，并在 Docker 可用时验证 Docker Compose。
## IDE 设置
默认架构是一个共享的 Docker 服务：
```text
http://localhost:8080/mcp
```
每个 IDE 都应该发送一个稳定的 `X-Client-ID` 头部，以便遥测、会话和预算按调用者分开。
### VS Code
```json
{
"servers": {
"unigrok": {
"type": "http",
"url": "http://localhost:8080/mcp",
"headers": { "X-Client-ID": "vscode" }
}
}
}
```
### Claude Desktop
Claude Desktop 配置文件服务器是 stdio 命令，因此使用 `mcp-remote` 桥接到 HTTP：
```json
{
"mcpServers": {
"unigrok": {
"command": "npx",
"args": [
"-y", "mcp-remote", "http://localhost:8080/mcp",
"--header", "X-Client-ID: claude-desktop"
]
}
}
}
```
### Claude Code
```bash
claude mcp add --transport http unigrok http://localhost:8080/mcp \
--header "X-Client-ID: claude-code"
```
### Codex
```toml
[mcp_servers.grok]
url = "http://localhost:8080/mcp"
http_headers = { "X-Client-ID" = "codex" }
```
如果在 `.env` 中设置了 `UNIGROK_API_KEYS`，还需要在每个客户端配置中添加 `Authorization: Bearer <token>`。
更多详细信息，包括 Antigravity/Gemini 注意事项，请参见 [docs/ide-setup.md](docs/ide-setup.md)。
## 运行模式
Stdio MCP：
```bash
uv run python main.py
```
HTTP 网关：
```bash
uv run python main.py --http
```
打包控制台脚本：
```bash
uv run unigrok-mcp init
uv run unigrok-mcp --http
```
受控辅助程序：
```bash
./grok-mcp-helper.sh init
./grok-mcp-helper.sh start
./grok-mcp-helper.sh status
```
## 工具界面
从 `agent` 开始。它是主要的工具，应该处理大多数非平凡请求。
核心工具：
- `agent`：自动路由 Grok 代理，模式为 `auto`、`fast`、`reasoning`、`thinking` 和 `research`。
- `grok_reflect`：专注于计划、代码审查笔记、输出和架构决策的结构化批评。
- `chat`：普通的 Grok 聊天，可选模型固定和会话历史。
- `chat_with_vision`：图像分析。
- `chat_with_files`：基于上传的 xAI 文件的可靠答案。
- `submit_research_job`、`get_research_job`、`list_research_jobs`：延迟的 xAI 研究作业。
- `remember_fact`、`search_knowledge`、`forget_fact`、`distill_session`：本地知识记忆。
- `web_search`、`x_search`、`remote_code_execution`：xAI 服务器端工具。
- `read_local_file`、`list_project_files`：工作区检查。
- `git_status`、`git_diff`、`git_log`、`git_show`：只读 Git 上下文。
- `generate_image`、`generate_video`、`extend_video`：Grok Imagine 媒体。
公共 Streamable HTTP MCP 端点故意公开用于 IDE 使用的统一 `agent` 接口。完整的 stdio 服务器公开了更广泛的工具集，用于本地受信任的工作流。
## 架构
UniGrok 有三个边界：
- 传输：stdio MCP、Streamable HTTP MCP 和 OpenAI 兼容的 `/v1` 外观都路由到同一个代理托管。
- 模型平面：API 支持的 Grok 模型是主要的；经过身份验证的本地 Grok CLI 可以在可用时提供 CLI 平面模型。
- 本地状态：SQLite 存储会话、遥测、研究作业、任务内存和蒸馏知识，在配置的状态目录下。
```mermaid
flowchart LR
CC[Claude Code] --> GW
VS[VS Code] --> GW
CX[Codex] --> GW
AG[Antigravity] --> GW
GW["UniGrok 网关<br/>localhost:8080<br/>/mcp · /v1 · /ui"]
GW -->|API 平面 · XAI_API_KEY| API["xAI API<br/>grok-4.5 · grok-build-0.1"]
GW -->|CLI 平面 · OAuth 订阅| CLI["Grok CLI<br/>grok-build 512k · composer"]
GW --- ST[("SQLite<br/>会话 · 成本 · 作业")]
```
完整设计细节见 [architecture.md](architecture.md)。
HTTP 模式下的有用端点：
- `GET /healthz`
- `GET /readyz`
- `GET /metrics`
- `GET /metrics?format=prometheus`
- `GET /v1/models`
- `POST /v1/chat/completions`
- `POST /mcp`
## WebMCP 与 OKF 发现
UniGrok 将谷歌的 **Open Knowledge Format (OKF)** 与实验性的 **WebMCP** API 结合起来，目前该 API 作为 W3C Web Machine Learning Community Group 草案发布。WebMCP 尚不是 W3C 标准。
### 1. OKF 知识包
`/docs/okf/` 目录包含一个自我描述的文档包，用于代理：
- `okf-manifest.json`：列出索引和主题文档。
- `index.md`：代理阅读的主要入口。
- 特定主题的文件（例如 `agent-tool.md`、`reasoning-guard.md`）详细介绍工具模式、输入/输出、模型固定和遥测预算控制。
### 2. WebMCP 启用文档与控制台
当运行 HTTP 网关时，访问 `http://localhost:8080/ui/` 会在 `document.modelContext` 下公开基于浏览器的 WebMCP 工具。
访问此页面的任何代理都可以自动发现和调用：
- `get_schema(tool_name)`：返回给定 UniGrok 工具的 Pydantic JSON 模式。
- `example_call(mode)`：为不同操作模式返回 JSON 模板/示例。
- `simulate_reasoning_guard`：模拟检查模型是否满足所需的推理级别。
- `fetch_okf_bundle`：返回 OKF 包中的元数据和文件路径。
### 3. 预访问清单发现
项目特定的实验性清单在 `/.well-known/webmcp` 处公开，以便兼容的代理和扩展可以在执行大量 DOM 抓取之前预先发现页面的功能：
```bash
curl -s http://localhost:8080/.well-known/webmcp
```
### 4. 运行 WebMCP 兼容浏览器或桥接
要让 IDE 代理调用这些实验性浏览器工具，请使用公开 `document.modelContext` 的浏览器构建或扩展，并保持目标选项卡在 `http://localhost:8080/ui/` 打开。
## 安全模型
- `XAI_API_KEY` 属于 UniGrok 服务器/容器环境，而不属于每个 IDE 客户端。
- `example.env` 仅为模板。运行时加载 `.env`（如果存在）并拒绝占位符密钥。
- Docker 默认发布 `127.0.0.1:8080`。
- 在将网关暴露到环回之外之前，请设置 `UNIGROK_API_KEYS`。
- 除非本地运行时标志明确启用，否则 Git 写入工具将被禁用。
- 默认情况下，容器重启被禁用，仅应为具有 Docker 访问权限的受信任本地进程启用。
有关漏洞报告和部署指南，请参见 [SECURITY.md](SECURITY.md)。
## 开发
```bash
uv sync
uv run pytest
uv run python -m compileall -q src evals main.py
docker compose config
```
在发布更改之前运行完整的本地测试套件。可以使用以下命令运行离线评估：
```bash
uv run python -m evals run --check-baseline
```
有关贡献工作流程和 PR 期望，请参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
---
由 [@DavidLJohnston](https://x.com/DavidLJohnston?utm_source=github&utm_medium=readme&utm_campaign=unigrok&utm_content=footer-author) 构建
· 为 [Grok](https://grok.com/?utm_source=github&utm_medium=readme&utm_campaign=unigrok&utm_content=footer-grok) 构建
· 由 [xAI](https://x.ai/?utm_source=github&utm_medium=readme&utm_campaign=unigrok&utm_content=footer-brand) 提供支持
· 在 X 上关注 [@xai](https://x.com/xai?utm_source=github&utm_medium=readme&utm_campaign=unigrok&utm_content=footer-x)
