使用说明

grok-cli-mcp

MCP服务器封装了Grok CLI，通过模型上下文协议提供对Grok AI模型的无缝访问。

这是什么？

grok-cli-mcp 是一个模型上下文协议（MCP）充当MCP客户端（如Claude Code、Cline、Cursor）和 Grok CLI。它没有实现直接的API调用，而是利用官方的Grok CLI工具，提供：

三种专用工具: grok_query （一般查询）， grok_chat （多回合对话）， grok_code （代码生成）
简单配置：只需安装Grok CLI并设置API密钥
经得起未来考验：自动受益于CLI改进（OAuth、定价计划等）
最低限度的维护：无需跟踪Grok API更改

为什么要使用CLI包装器？

益处

✅ 利用现有工具：使用官方Grok CLI，确保兼容性和稳定性

✅ 未来的OAuth支持：当Grok CLI添加OAuth身份验证时，此包装器将自动支持它，而无需更改代码

✅ 固定定价计划：当Grok推出特定于CLI的计划，而不是按API代币付费时，可以从每月固定定价（如Codex/ChatGPT/Gemini）中受益

✅ 组织友好：在安全性和法规遵从性方面，许多组织更喜欢经审核的CLI工具，而不是直接的API集成

✅ 更简单的代码库：对于完整的API客户端实现，大约400行与1500+行

✅ 更少的依赖关系：没有HTTP客户端库、请求/响应处理或复杂的网络代码

✅ 自动更新：CLI错误修复和新功能无需更改代码即可传播

权衡

⚠️ 性能开销：额外的进程生成会为每个请求增加约50-200ms的延迟

⚠️ CLI依赖关系：需要安装Grok CLI并在PATH中

⚠️ 有限控制：无法访问CLI未公开的低级API功能

⚠️ 错误处理：CLI错误消息的结构可能不如API响应

⚠️ 无流媒体：仅限于CLI流媒体功能（如果有的话）

何时使用此

非常适合：

开发和原型制作工作流程
内部工具和自动化（<100要求/分钟）
偏好CLI工具而非API库的组织
便利性比毫秒更重要的工作流程
希望从未来CLI特定定价/功能中受益的团队

考虑直接API：

高通量生产系统（>1000需求/分钟）
延迟关键应用程序（要求<50ms）
CLI未公开的高级API功能
流媒体响应要求

先决条件

安装前 grok-cli-mcp，确保您拥有：

Grok CLI：从安装 X.AI的文档

# Installation instructions vary by platform
# See https://docs.x.ai/docs for latest instructions

Python 3.10+：检查您的版本
```
python3 --version
```
Grok API密钥：从获取 X.AI控制台

安装

选项1：从PyPI安装（推荐）

pip install grok-cli-mcp

选项2：使用uv进行安装

uv pip install grok-cli-mcp

选项3：使用pipx安装（隔离环境）

pipx install grok-cli-mcp

选项4：从源代码安装

git clone https://github.com/BasisSetVentures/grok-cli-mcp.git
cd grok-cli-mcp
pip install -e .

选项5：开发安装

git clone https://github.com/BasisSetVentures/grok-cli-mcp.git
cd grok-cli-mcp
pip install -e ".[dev]"

快速开始

1.设置您的环境

# Required: Set your Grok API key
export GROK_API_KEY="your-api-key-here"

# Optional: Specify custom Grok CLI path
export GROK_CLI_PATH="/custom/path/to/grok"

要进行永久设置，请添加到您的shell配置文件中(~/.bashrc, ~/.zshrc等等）：

echo 'export GROK_API_KEY="your-api-key-here"' >> ~/.bashrc
source ~/.bashrc

2.测试服务器

# Run the server directly
python -m grok_cli_mcp

# Or use the command
grok-mcp

# Should start and wait for stdin (Ctrl+C to exit)

3.配置MCP客户端

克劳德代码

添加到您的 .mcp.json:

{
  "mcpServers": {
    "grok": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "grok_cli_mcp"],
      "env": {
        "GROK_API_KEY": "your-api-key-here"
      }
    }
  }
}

对于Cline（VS代码）

添加到 ~/.cline/mcp_settings.json:

{
  "mcpServers": {
    "grok": {
      "command": "python",
      "args": ["-m", "grok_cli_mcp"],
      "env": {
        "GROK_API_KEY": "your-api-key-here"
      }
    }
  }
}

对于光标

添加到 ~/.cursor/mcp.json:

{
  "grok": {
    "command": "python",
    "args": ["-m", "grok_cli_mcp"],
    "env": {
      "GROK_API_KEY": "your-api-key-here"
    }
  }
}

⚠️ 安全警告：永远不要将API密钥提交到版本控制。使用环境变量或机密管理器。

使用示例

工具：grok_query

向Grok发送一个简单的提示：

{
  "tool": "grok_query",
  "arguments": {
    "prompt": "Explain quantum computing in simple terms",
    "model": "grok-code-fast-1",
    "timeout_s": 120
  }
}

回应：Grok的纯文本回答

工具：grok_chat

带有消息历史记录的多回合对话：

{
  "tool": "grok_chat",
  "arguments": {
    "messages": [
      {"role": "user", "content": "What is MCP?"},
      {"role": "assistant", "content": "MCP is Model Context Protocol..."},
      {"role": "user", "content": "How does it work?"}
    ],
    "model": "grok-code-fast-1",
    "timeout_s": 120
  }
}

回应：考虑到对话历史，Grok的回答

工具：grok_code

使用语言提示和上下文生成代码：

{
  "tool": "grok_code",
  "arguments": {
    "task": "Create a Python function to parse JSON with error handling",
    "language": "python",
    "context": "Using standard library only, no external dependencies",
    "timeout_s": 180
  }
}

回应：完整、可用的Python代码及其解释

高级：原始输出模式

获取包含完整细节的结构化响应：

{
  "tool": "grok_query",
  "arguments": {
    "prompt": "Explain async/await",
    "raw_output": true
  }
}

回应:

{
  "text": "Async/await is...",
  "messages": [{"role": "assistant", "content": "..."}],
  "raw": "...",
  "model": "grok-code-fast-1"
}

配置

环境变量

变量	必填	默认	描述
`GROK_API_KEY`	是	-	来自X.AI控制台的Grok API密钥
`GROK_CLI_PATH`	没有	`/opt/homebrew/bin/grok`	Grok CLI二进制文件的路径

模型选择

可用型号（截至2025-12）：

grok-code-fast-1 -代码任务的快速模型
grok-2 -一般任务的主要模型
其他型号 Grok CLI文档

在每次工具调用中指定模型，或省略CLI默认值。

超时配置

按工具分类的默认超时：

grok_query：120秒
grok_chat：120秒
grok_code：180秒

通过以下方式进行调整 timeout_s 复杂任务的参数。

故障排除

“未找到Grok CLI”

问题：服务器找不到Grok CLI二进制文件

解决方案:

验证安装：
```
which grok
```
设置显式路径：
```
export GROK_CLI_PATH="/path/to/grok"
```
添加到路径：
```
export PATH="$PATH:/opt/homebrew/bin"
```

“未设置GROK_API_KEY”

问题：API密钥不在环境中

解决方案:

壳内导出：
```
export GROK_API_KEY="xai-..."
```

添加到shell配置文件(.bashrc, .zshrc):

echo 'export GROK_API_KEY="xai-..."' >> ~/.zshrc
source ~/.zshrc

使用 .env 使用python dotenv的文件（请参见 examples/.env.example)

“Grok CLI超时”

问题：请求时间过长

解决方案:

增加超时时间：
```
{"timeout_s": 300}
```
简化提示或分解为更小的请求
检查网络连接

JSON解析错误

问题：CLI输出不是有效的JSON

解决方案:

将Grok CLI更新到最新版本：

# Update instructions vary by installation method

检查CLI警告/错误
使用 raw_output=true 要查看原始CLI响应：
```
{"raw_output": true}
```

权限错误

问题：无法执行Grok CLI

解决方案:

使CLI可执行：
```
chmod +x /path/to/grok
```
检查文件所有权和权限
验证CLI是否独立工作：
```
grok -p "test"
```

有关更多解决方案，请参阅 docs/故障排除.md.

安全最佳实践

永远不要泄露秘密

❌ 不要：

提交 .env 带有真正API密钥的文件
在中包含API密钥 .mcp.json 由git跟踪
在问题或提取请求中共享API密钥
Python文件中的硬编码键

✅ 做：

使用环境变量： export GROK_API_KEY="..."
使用shell RC文件： ~/.bashrc, ~/.zshrc
在生产中使用机密管理器：AWS机密管理器、HashiCorp Vault
如果意外暴露，请立即旋转按键

获取API密钥

访问 X.AI控制台
使用您的X.AI帐户登录
导航到API密钥部分
生成新密钥
安全存储（1Password、Bitwarden等）
设置为环境变量

关键点旋转

如果您意外暴露了API密钥：

立即在X.AI控制台中撤销密钥
生成新密钥
更新环境变量
检查暴露密钥的git历史记录
考虑使用以下工具 gitleaks 扫描秘密

报告安全问题

不要公开安全漏洞问题。

请通过GitHub安全公告或直接联系维护人员负责任地报告安全问题。

建筑与设计

该项目遵循 CLI包装器模式 而不是直接的API集成。关键设计决策：

进程分离：每个Grok请求都会生成一个子流程用于CLI执行
JSON解析与回退：尝试结构化解析，返回原始输出
上下文传播：使用FastMCP的上下文进行日志记录和进度更新
异步执行：对于非阻塞行为，所有操作都是异步优先的

有关详细的体系结构讨论，请参见 docs/architecture.md.

发展

运行测试

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage
pytest --cov=grok_cli_mcp --cov-report=html

# Run specific test file
pytest tests/test_utils.py

代码格式化

# Format code
black .

# Lint code
ruff check --fix .

类型检查

mypy src/

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

请确保:

测试通过(pytest)
代码已格式化(black, ruff)
类型提示正确(mypy)
文档已更新

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

致谢

内置于 FastMCP 耶利米·洛因
用途模型上下文协议 Anthropic的SDK
包裹 Grok CLI 来自X.AI

支持

文档: 自述文件 • 建筑 • 故障排除
问题: GitHub问题
讨论: GitHub讨论
Grok文件: docs.x.ai

由……制造基础投资 使用克劳德代码和FastMCP

使用说明

grok-cli-mcp

这是什么？

为什么要使用CLI包装器？

益处

权衡

何时使用此

先决条件

安装

选项1：从PyPI安装（推荐）

选项2：使用uv进行安装

选项3：使用pipx安装（隔离环境）

选项4：从源代码安装

选项5：开发安装

快速开始

1.设置您的环境

2.测试服务器

3.配置MCP客户端

克劳德代码

对于Cline（VS代码）

对于光标

使用示例

工具：grok_query

工具：grok_chat

工具：grok_code

高级：原始输出模式

配置

环境变量

模型选择

超时配置

故障排除

“未找到Grok CLI”

“未设置GROK_API_KEY”

“Grok CLI超时”

JSON解析错误

权限错误

安全最佳实践

永远不要泄露秘密

获取API密钥

关键点旋转

报告安全问题

建筑与设计

发展

运行测试

代码格式化

类型检查

贡献

许可证

致谢

支持

相关 MCP

Unity MCP AI游戏开发工具

MATLAB代码执行与生成服务

Claude代码MCP服务器

Python代码执行器

微博数据服务

Ionic开发工具服务器