Grok Cli MCP

🚀 grok-cli-mcp

grok-cli-mcp 是一个基于 Model Context Protocol (MCP) 的服务器，它作为一座桥梁，连接了 MCP 客户端（如 Claude Code、Cline、Cursor）和 Grok CLI。借助官方的 Grok CLI 工具，它为用户提供了无缝访问 Grok AI 模型的途径。

🚀 快速开始

1. 环境设置

# 必需：设置你的 Grok API 密钥
export GROK_API_KEY="your-api-key-here"

# 可选：指定自定义 Grok CLI 路径
export GROK_CLI_PATH="/custom/path/to/grok"

若要进行永久设置，可将上述命令添加到你的 shell 配置文件（如 ~/.bashrc、~/.zshrc 等）中：

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

2. 测试服务器

# 直接运行服务器
python -m grok_cli_mcp

# 或者使用命令
grok-mcp

# 服务器应启动并等待标准输入（按 Ctrl+C 退出）

3. 为 MCP 客户端进行配置

对于 Claude Code

在你的 .mcp.json 文件中添加以下内容：

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

对于 Cline (VS Code)

在 ~/.cline/mcp_settings.json 文件中添加以下内容：

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

对于 Cursor

在 ~/.cursor/mcp.json 文件中添加以下内容：

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

⚠️ 重要提示

切勿将 API 密钥提交到版本控制系统中。建议使用环境变量或密钥管理工具来存储 API 密钥。

✨ 主要特性

• 三种专用工具：grok_query（用于一般查询）、grok_chat（用于多轮对话）、grok_code（用于代码生成）
• 配置简单：只需安装 Grok CLI 并设置 API 密钥
• 面向未来：可自动受益于 CLI 的改进（如 OAuth、定价计划等）
• 维护成本低：无需跟踪 Grok API 的变化

📦 安装指南

选项 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]"

💻 使用示例

基础用法

工具：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"
}

📚 详细文档

配置

环境变量

模型选择

截至 2025 年 12 月，可用的模型如下：

• grok-code-fast-1 - 用于代码任务的快速模型
• grok-2 - 用于一般任务的主要模型
• 其他模型可参考 Grok CLI 文档

可在每个工具调用中指定模型，若不指定则使用 CLI 默认模型。

超时配置

各工具的默认超时时间如下：

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

对于复杂任务，可通过 timeout_s 参数调整超时时间。

故障排除

"Grok CLI not found"

问题：服务器无法找到 Grok CLI 二进制文件 解决方案：

1. 验证安装情况：

   which grok
   

2. 设置明确的路径：

   export GROK_CLI_PATH="/path/to/grok"
   

3. 将其添加到 PATH 中：

   export PATH="$PATH:/opt/homebrew/bin"
   

"GROK_API_KEY is not set"

问题：环境中未设置 API 密钥 解决方案：

1. 在 shell 中导出：

   export GROK_API_KEY="xai-..."
   

2. 添加到 shell 配置文件（.bashrc、.zshrc）中：

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

3. 使用 .env 文件和 python-dotenv（可参考 examples/.env.example）

"Grok CLI timed out"

问题：请求耗时过长 解决方案：

1. 增加超时时间：

   {"timeout_s": 300}
   

2. 简化提示或拆分为较小的请求
3. 检查网络连接

JSON 解析错误

问题：CLI 输出不是有效的 JSON 解决方案：

1. 将 Grok CLI 更新到最新版本：

   # 更新说明因安装方法而异
   

2. 检查 CLI 警告/错误信息
3. 使用 raw_output=true 查看原始 CLI 响应：

   {"raw_output": true}
   

权限错误

问题：无法执行 Grok CLI 解决方案：

1. 使 CLI 可执行：

   chmod +x /path/to/grok
   

2. 检查文件所有权和权限
3. 验证 CLI 独立运行是否正常：

   grok -p "test"
   

更多解决方案可参考 docs/troubleshooting.md。

安全最佳实践

切勿提交机密信息

❌ 不要这样做：

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

✅ 应该这样做：

• 使用环境变量：export GROK_API_KEY="..."
• 使用 shell 配置文件：~/.bashrc、~/.zshrc
• 在生产环境中使用密钥管理工具：如 AWS Secrets Manager、HashiCorp Vault
• 若 API 密钥意外泄露，立即轮换密钥

获取 API 密钥

1. 访问 X.AI 控制台
2. 使用你的 X.AI 账户登录
3. 导航到 API 密钥部分
4. 生成一个新密钥
5. 安全存储（如使用 1Password、Bitwarden 等）
6. 设置为环境变量

密钥轮换

若你意外泄露了 API 密钥：

1. 立即在 X.AI 控制台中撤销该密钥
2. 生成一个新密钥
3. 更新环境变量
4. 检查 git 历史记录中是否有泄露的密钥
5. 考虑使用 gitleaks 等工具扫描机密信息

报告安全问题

请勿公开提交安全漏洞相关的问题。 请通过 GitHub 安全通告或直接联系维护者，负责任地报告安全问题。

🔧 技术细节

本项目采用 CLI 包装器模式，而非直接进行 API 集成。主要的设计决策如下：

1. 进程隔离：每个 Grok 请求都会生成一个子进程来执行 CLI
2. 带有回退机制的 JSON 解析：尝试进行结构化解析，若失败则回退到原始输出
3. 上下文传播：使用 FastMCP 的上下文进行日志记录和进度更新
4. 异步执行：所有操作都优先采用异步方式，以实现非阻塞行为

详细的架构讨论可参考 docs/architecture.md。

📄 许可证

本项目遵循 MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

• 基于 FastMCP 构建，作者为 Jeremiah Lowin
• 使用了 Model Context Protocol SDK，由 Anthropic 提供
• 封装了来自 X.AI 的 Grok CLI

支持

• 文档：README • 架构 • 故障排除
• 问题反馈：GitHub Issues
• 讨论交流：GitHub Discussions
• Grok 文档：docs.x.ai

由 Basis Set Ventures 借助 Claude Code 和 FastMCP 开发