内容
# grok-oauth-mcp
独立的TypeScript标准输入输出MCP服务器，用于xAI Grok，支持网页OAuth PKCE。适用于本地MCP客户端，如Claude Desktop、兼容MCP的主机以及其他标准输入输出MCP启动器。
该服务器在正常使用情况下不需要`XAI_API_KEY`。主要的认证路径是xAI网页OAuth，带有本地令牌存储。
## 要求
- Node.js 20+
- 本地MCP客户端，可以启动标准输入输出服务器，如Claude Desktop或其他兼容MCP的主机。
- xAI账户，拥有有效的**SuperGrok**订阅或与您登录的X账户关联的**X Premium+**订阅。这与Hermes xAI Grok OAuth连接器匹配：浏览器登录通过`accounts.x.ai`进行，xAI自动将X Premium+权益链接到xAI会话。
在正常OAuth路径中，不使用`XAI_API_KEY`。xAI可能仍会根据订阅级别限制OAuth API访问；如果OAuth成功但xAI API调用返回`403`，您的账户可能尚未获得该OAuth API服务的权益。
## 功能
- 使用Hermes客户端ID的xAI网页OAuth PKCE登录。
- 默认情况下，在`~/.config/grok-oauth-mcp/tokens.json`存储令牌。
- 使用`GROK_OAUTH_MCP_CONFIG_DIR`配置令牌目录。
- 访问令牌过期前的刷新令牌流程。
- 使用`XAI_BASE_URL`配置xAI API基准，默认为`https://api.x.ai/v1`。
- 用于认证、Grok聊天、X搜索、图像、视频、TTS和转录的MCP标准输入输出工具。
- 支持本地图像/音频路径的多部分上传。
## 快速入门
这是人类或代理启动MCP、认证并验证Grok可用的最短路径。
### 1. 安装
从源码：
```bash
git clone https://github.com/bowtieswan/grok-oauth-mcp.git
cd grok-oauth-mcp
npm install
npm run build
```
直接从构建的checkout运行：
```bash
node /absolute/path/to/grok-oauth-mcp/dist/index.js
```
或从checkout全局安装：
```bash
npm install -g .
grok-oauth-mcp
```
软件包运行器表单：
```bash
npx grok-oauth-mcp
```
### 2. 添加到您的MCP客户端
尽可能使用绝对路径。这避免了您的shell和GUI应用程序之间的PATH差异。
#### Claude Desktop
添加一个MCP服务器条目，指向您的本地构建或全局可执行文件。本地构建示例：
```json
{
"mcpServers": {
"grok-oauth": {
"command": "node",
"args": ["/absolute/path/to/grok-oauth-mcp/dist/index.js"]
}
}
}
```
如果您已全局安装并知道可执行路径：
```json
{
"mcpServers": {
"grok-oauth": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/grok-oauth-mcp"]
}
}
}
```
#### OpenCode
在您的OpenCode配置中添加一个本地MCP服务器条目，通常是`~/.config/opencode/opencode.json`，在顶级`mcp`对象下：
```json
{
"mcp": {
"grok-oauth": {
"command": [
"/absolute/path/to/node",
"/absolute/path/to/grok-oauth-mcp"
],
"enabled": true,
"type": "local"
}
}
}
```
然后重启MCP客户端或重新加载MCP服务器。在OpenCode中，通过以下命令验证发现：
```bash
opencode mcp list
```
您应该看到`grok-oauth`已连接。
### 3. 认证
首先使用`auth_login`工具，设置`wait=false`。对于大多数MCP客户端，这是最安全的模式，因为工具立即返回URL。
输入：
```json
{
"wait": false,
"timeout_ms": 600000
}
```
结果包含：
- `auth_url`: 在浏览器中打开此URL。
- `state`: 此尝试的OAuth状态。
- `redirect_uri`: 通常为`http://127.0.0.1:56121/callback`。
- `token_path`: 成功后将写入令牌的位置。
打开`auth_url`，登录xAI，然后完成以下两个路径之一。
#### 路径A：浏览器重定向到本地主机
如果浏览器重定向到`http://127.0.0.1:56121/callback?...`并显示成功消息，则登录完成。运行`auth_status`以确认。
#### 路径B：xAI显示Grok构建代码
有时，xAI会显示一个页面，内容如下：
```text
输入此代码以完成登录
将以下代码复制到Grok Build中以完成登录
```
如果发生这种情况，请复制代码并立即调用`auth_exchange_code`：
```json
{
"code": "paste-the-grok-build-code-here"
}
```
代码与最近的`auth_login`尝试和保存的PKCE验证器绑定。如果代码过期或您启动了另一个登录尝试，请再次运行`auth_login`并使用新的URL/代码。
如果您有完整的回调URL而不是裸代码，请将其作为`callback_url`传递：
```json
{
"callback_url": "http://127.0.0.1:56121/callback?code=...&state=..."
}
```
### 4. 验证认证
运行`auth_status`。成功的登录返回`authenticated: true`、`has_refresh_token: true`和过期时间。令牌值永远不会返回。
令牌存储在：
```text
~/.config/grok-oauth-mcp/tokens.json
```
临时待处理OAuth状态存储在：
```text
~/.config/grok-oauth-mcp/pending_oauth.json
```
两个文件都以模式`0600`写入，其中本地文件系统支持POSIX权限。
### 5. 测试Grok
在`auth_status`认证后，尝试一个小调用。对于X搜索：
```json
{
"query": "最新的xAI Grok更新",
"filters": {
"max_results": 5
}
}
```
如果第一次广泛搜索超时，请重试并使用更窄的查询和更少的結果。
## OAuth详细信息
- 发现：`https://auth.x.ai/.well-known/openid-configuration`
- 显示的授权服务器：`accounts.x.ai`
- 客户端ID：`b1a00492-073a-47ea-816f-4c329264a828`
- 范围：`openid profile email offline_access grok-cli:access api:access`
- 重定向URI：`http://127.0.0.1:56121/callback`
- 授权URL包含`plan=generic`和`referrer=hermes-agent`。
## 代理认证说明
- 优先使用`auth_login`并设置`wait=false`。除非您的MCP主机显示stderr或工具输出，否则不要使用`wait=true`。
- 始终打开最新`auth_login`结果中的确切`auth_url`。
- 如果页面显示Grok构建代码，请调用`auth_exchange_code`并输入该代码。不要尝试手动打开`/callback`。
- 如果`auth_exchange_code`返回`No pending OAuth login found`或`Pending OAuth login is expired`，请再次运行`auth_login`并使用新的URL/代码。
- 如果xAI返回`invalid_grant`，则代码已过期、已使用或属于不同的登录尝试。请再次运行`auth_login`。
## 工具
### `auth_login`
启动OAuth登录并返回授权URL。
输入：
```json
{
"wait": false,
"timeout_ms": 300000
}
```
仅当客户端可以显示stderr或在调用仍在运行时显示工具输出时，才设置`wait=true`。
### `auth_exchange_code`
兑换粘贴的xAI/Grok构建OAuth代码或完整的回调URL，使用上一次`auth_login`调用的待处理PKCE状态。
输入带有裸Grok构建代码：
```json
{
"code": "paste-the-grok-build-code-here"
}
```
输入带有回调URL：
```json
{
"callback_url": "http://127.0.0.1:56121/callback?code=...&state=..."
}
```
### `auth_status`
报告是否存储了令牌、是否存在刷新令牌以及近似过期时间。令牌值永远不会返回。
### `auth_logout`
删除本地令牌文件和任何待处理的OAuth状态。
### `grok_chat`
发布到`/responses`，设置`store=false`。默认模型：`grok-build-0.1`。
示例：
```json
{
"input": "解释这个MCP服务器可以做什么。"
}
```
### `x_search`
发布到`/responses`，设置`tools: [{ "type": "x_search" }]`和可选筛选器。
示例：
```json
{
"query": "最新的xAI Grok更新",
"filters": {
"max_results": 5
}
}
```
### `grok_tts`
发布到`/tts`。
示例：
```json
{
"text": "你好，来自Grok。",
"voice_id": "eve",
"language": "en"
}
```
### `grok_image`
发布到`/images/generations`用于文本到图像，发布到`/images/edits`当存在`image_path`时。
默认值：
- 生成模型：`grok-imagine-image`
- 编辑模型：`grok-imagine-image-quality`
常见的图像选项包括`aspect_ratio`、`resolution`、`size`、`n`和`response_format`。传递当前xAI/Hermes图像界面支持的值，例如常见的宽高比，如`1:1`、`16:9`、`9:16`、`4:3`和`3:4`（当在您的帐户上可用时）。
### `grok_video`
发布到`/videos/generations`。支持文本到视频和图像到视频，当存在`image_path`时。
默认值：
- 文本到视频模型：`grok-imagine-video`
- 图像到视频模型：`grok-imagine-video-1.5-preview`
设置`poll=true`以轮询`/videos/{request_id}`直到请求离开队列或处理状态。
### `grok_transcribe`
将本地音频文件发布到`/stt`，使用多部分表单数据，匹配xAI Grok STT。
示例：
```json
{
"file_path": "/path/to/audio.wav",
"language": "en"
}
```
## 故障排除
- `Not authenticated. Run auth_login first.`：运行`auth_login`并设置`wait=false`，打开返回的`auth_url`，然后完成重定向或使用`auth_exchange_code`输入Grok构建代码。
- 浏览器无法访问回调：如果xAI显示Grok构建代码，请不要手动打开`/callback`；相反，调用`auth_exchange_code`输入代码。如果您期望重定向，请确保没有其他内容正在使用端口`56121`，然后再次运行`auth_login`。
- `No pending OAuth login found`或`Pending OAuth login is expired`：再次运行`auth_login`并使用新的URL/代码。
- `invalid_grant`：粘贴的代码已过期、已使用或属于不同的登录尝试。再次运行`auth_login`。
- 来自xAI的`403`：您的xAI账户可能没有所需的SuperGrok或X Premium+权益，适用于请求的Grok API服务。
- 令牌刷新失败：运行`auth_logout`，然后再次运行`auth_login`。
- 自定义API网关或模拟服务器：设置`XAI_BASE_URL`为替换基准URL。
- 自定义令牌位置：设置`GROK_OAUTH_MCP_CONFIG_DIR`为目录路径。服务器在其中写入`tokens.json`。
## 开发
```bash
npm test
npm run build
```
测试模拟所有OAuth和xAI网络调用。它们不得调用真实的xAI OAuth或xAI API。
## 许可证
MIT
