grok-cli-mcp
](https://badge.fury.io/py/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流媒体功能（如果有的话）
何时使用此
非常适合：
- 开发和原型制作工作流程
- 内部工具和自动化（\1000需求/分钟）
- 延迟关键应用程序（要求\> ~/.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文档](https://docs.x.ai/docs)
在每次工具调用中指定模型，或省略CLI默认值。
### 超时配置
按工具分类的默认超时：
- `grok_query`：120秒
- `grok_chat`：120秒
- `grok_code`：180秒
通过以下方式进行调整 `timeout_s` 复杂任务的参数。
## 故障排除
### “未找到Grok CLI”
**问题**：服务器找不到Grok CLI二进制文件
**解决方案**:
1. 验证安装：which grok
1. 设置显式路径：export GROK_CLI_PATH="/path/to/grok"
1. 添加到路径：export PATH="$PATH:/opt/homebrew/bin"
### “未设置GROK_API_KEY”
**问题**：API密钥不在环境中
**解决方案**:
1. 壳内导出：export GROK_API_KEY="xai-..."
1. 添加到shell配置文件(`.bashrc`, `.zshrc`):echo 'export GROK_API_KEY="xai-..."' >> ~/.zshrc source ~/.zshrc
1. 使用 `.env` 使用python dotenv的文件（请参见 `examples/.env.example`)
### “Grok CLI超时”
**问题**：请求时间过长
**解决方案**:
1. 增加超时时间：{"timeout_s": 300}
1. 简化提示或分解为更小的请求
1. 检查网络连接
### JSON解析错误
**问题**：CLI输出不是有效的JSON
**解决方案**:
1. 将Grok CLI更新到最新版本：# Update instructions vary by installation method
1. 检查CLI警告/错误
1. 使用 `raw_output=true` 要查看原始CLI响应：{"raw_output": true}
### 权限错误
**问题**：无法执行Grok CLI
**解决方案**:
1. 使CLI可执行：chmod +x /path/to/grok
1. 检查文件所有权和权限
1. 验证CLI是否独立工作：grok -p "test"
有关更多解决方案，请参阅 [docs/故障排除.md](docs/troubleshooting.md).
## 安全最佳实践
### 永远不要泄露秘密
**❌ 不要：**
- 提交 `.env` 带有真正API密钥的文件
- 在中包含API密钥 `.mcp.json` 由git跟踪
- 在问题或提取请求中共享API密钥
- Python文件中的硬编码键
**✅ 做：**
- 使用环境变量： `export GROK_API_KEY="..."`
- 使用shell RC文件： `~/.bashrc`, `~/.zshrc`
- 在生产中使用机密管理器：AWS机密管理器、HashiCorp Vault
- 如果意外暴露，请立即旋转按键
### 获取API密钥
1. 访问 [X.AI控制台](https://console.x.ai/)
1. 使用您的X.AI帐户登录
1. 导航到API密钥部分
1. 生成新密钥
1. 安全存储（1Password、Bitwarden等）
1. 设置为环境变量
### 关键点旋转
如果您意外暴露了API密钥：
1. **立即** 在X.AI控制台中撤销密钥
1. 生成新密钥
1. 更新环境变量
1. 检查暴露密钥的git历史记录
1. 考虑使用以下工具 `gitleaks` 扫描秘密
### 报告安全问题
**不要** 公开安全漏洞问题。
请通过GitHub安全公告或直接联系维护人员负责任地报告安全问题。
## 建筑与设计
该项目遵循 **CLI包装器模式** 而不是直接的API集成。关键设计决策：
1. **进程分离**：每个Grok请求都会生成一个子流程用于CLI执行
1. **JSON解析与回退**：尝试结构化解析，返回原始输出
1. **上下文传播**：使用FastMCP的上下文进行日志记录和进度更新
1. **异步执行**：对于非阻塞行为，所有操作都是异步优先的
有关详细的体系结构讨论，请参见 [docs/architecture.md](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/
## 贡献
欢迎投稿！拜托：
1. 分叉存储库
1. 创建要素分支(`git checkout -b feature/amazing-feature`)
1. 提交您的更改(`git commit -m 'Add amazing feature'`)
1. 推到分支(`git push origin feature/amazing-feature`)
1. 打开拉取请求
**请确保**:
- 测试通过(`pytest`)
- 代码已格式化(`black`, `ruff`)
- 类型提示正确(`mypy`)
- 文档已更新
## 许可证
此项目根据MIT许可证获得许可-请参阅 [许可证](LICENSE) 文件以获取详细信息。
## 致谢
- 内置于 [FastMCP](https://github.com/jlowin/fastmcp) 耶利米·洛因
- 用途 [模型上下文协议](https://modelcontextprotocol.io) Anthropic的SDK
- 包裹 [Grok CLI](https://docs.x.ai/docs) 来自X.AI
## 支持
- **文档**: [自述文件](README.md) • [建筑](docs/architecture.md) • [故障排除](docs/troubleshooting.md)
- **问题**:
- **讨论**:
- **Grok文件**: [docs.x.ai](https://docs.x.ai/docs)
______________________________________________________________________
**由……制造 [基础投资](https://github.com/BasisSetVentures)** 使用克劳德代码和FastMCP