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 開發