Grok-MCP

用于 xAI Grok API 的 MCP 服务器，支持智能体工具调用、图像和视频生成、视觉识别以及文件处理。

功能特性

• 智能体工具调用：支持网页搜索、X 搜索以及具备多步推理能力的代执行。

• 多种 Grok 模型：可访问最新模型，如 grok-4.20-0309-reasoning、grok-4-1-fast-reasoning 等。

• 图像和视频生成：使用 Grok Imagine 创建图像和视频。

• 视觉能力：使用 Grok 的视觉模型分析图像。

• 文件 API：上传、管理文档并进行对话。

• 有状态对话：通过 ID 在多个请求间保持对话上下文。

• 本地聊天记录：可选择将客户端聊天记录以 JSON 文件形式持久化保存在 chats/ 目录中。

Related MCP server: Zen MCP Server

前置要求

• Python 3.11 或更高版本

• xAI API 密钥（在此获取）

• Astral UV

安装

1. 克隆仓库：

git clone https://github.com/merterbak/Grok-MCP.git
cd Grok-MCP

2. 创建虚拟环境：

uv venv
source .venv/bin/activate # macOS/Linux or .venv\Scripts\activate on Windows

3. 安装依赖：

uv sync

配置

Claude Desktop 集成

将以下内容添加到您的 Claude Desktop 配置文件中：

{
  "mcpServers": {
    "grok": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/Grok-MCP",
        "run",
        "python",
        "main.py"
      ],
      "env": {
        "XAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code 集成

在项目目录内运行此命令：

claude mcp add grok-mcp -e XAI_API_KEY=your_api_key_here -- uv run --directory /path/to/Grok-MCP python main.py

或者，如果您有一个包含密钥的 .env 文件：

 claude mcp add grok-mcp -- uv run --directory /path/to/Grok-MCP python main.py

验证其是否已注册：

claude mcp list

文件系统 MCP（可选）

Claude Desktop 无法将聊天中上传的图像发送给 MCP 工具。直接从计算机访问文件的最简单方法是使用官方的 Filesystem MCP 服务器。设置完成后，您只需在聊天中输入图像的文件路径（例如 /Users/mert/Desktop/image.png），Claude 即可将其用于任何视觉聊天工具。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/<your-username>/Desktop",
        "/Users/<your-username>/Downloads"
      ]
    }
  }
}

对于 stdio：

uv run python main.py

Docker：

docker compose up --build

Mcp Inspector：

mcp dev main.py

可用工具

每个工具在 src/server.py 中都有完整的文档字符串，包含其参数和返回格式。MCP 客户端会直接显示这些信息，因此此列表仅作为可用功能的快速概览。

注意：要使用图像和文件，必须在聊天中提供路径。请参阅 文件系统 MCP（可选） 进行设置。

聊天与推理

• chat — 标准聊天补全，支持可选的持久化历史记录和多智能体支持。

• chat_with_vision — 使用 Grok 视觉模型分析本地或远程图像。

• chat_with_files — 基于先前上传的文档进行对话。

• stateful_chat — 通过 response_id 继续服务器端存储的对话。

• retrieve_stateful_response — 按 ID 获取存储的响应。

• delete_stateful_response — 按 ID 删除存储的响应。

智能体工具

• web_search — 具备域名过滤和引用功能的自主网页研究。

• x_search — 对 X (Twitter) 帖子的自主搜索，支持句柄和日期过滤。

• code_executor — 通过在沙盒中运行 Python 来解决任务。

• grok_agent — 统一智能体，结合了文件、图像、网页搜索、X 搜索和代码执行功能。

图像和视频

• generate_image — 使用 Grok Imagine 创建或编辑图像（支持多参考编辑）。

• generate_video — 使用 Grok Imagine 进行文本转视频、图像转视频或视频编辑。

• extend_video — 使用后续提示词扩展现有的生成视频。

文件

• upload_file — 上传本地文档。

• list_files — 列出已上传的文件并进行排序。

• get_file — 按 ID 获取文件元数据。

• get_file_content — 以文本形式下载文件内容。

• delete_file — 按 ID 删除文件。

本地聊天记录

• list_chat_sessions — 列出 chats/ 中保存的会话。

• get_chat_history — 获取会话的完整记录。

• clear_chat_history — 删除会话的本地历史记录文件。

模型

• list_models — 列出所有 Grok 语言和图像模型及其实时定价。

许可证

本项目为开源项目，采用 MIT 许可证。