Skip to content

xuxu777xu/ikuncode-aimcp

BranchesTags

Repository files navigation

ikuncode-aimcp

一个二进制，三套 AI 引擎 — Gemini · Codex · Grok

License: GPL-3.0 Rust

English

用 Rust 编写的统一 MCP 服务器，将 Gemini CLI、Codex CLI 和 Grok Search 整合到单个进程中。配置一次，即可在 Cursor / Windsurf / Claude Desktop 等任意 MCP 客户端中使用全部工具。

相关项目

项目 类型 适用场景
ikuncode-aimcp（本项目） MCP Server 所有 MCP 客户端通用，含 gemini_image 图像生成
IKunImage Claude Code Skill Claude Code 专用 — 文生图 / 图生图 / 并发批量生成
api.ikuncode.cc api.ikuncode.cc 提供稳定高效的 API 聚合中转服务，支持 Claude Code、Codex、Gemini 等主流模型。

特性

  • 一个二进制，全部工具 — 只需配置一个 MCP 服务器，取代三个
  • 运行时检测 — 启动时自动检测可用工具；不可用的工具在被调用时返回清晰的错误信息
  • AdaptiveStdio 传输 — 自动检测 JSONL 和 LSP 帧格式，最大化客户端兼容性
  • 纯 Rust 的 GrokSearch — 零 Python 依赖；通过 Grok API 实现 Web 搜索和内容抓取，支持 SSE 流式传输和重试

工具列表

工具 来源 描述
gemini Gemini CLI AI 驱动的任务执行，支持会话连续性
gemini_image Gemini CLI AI 图像生成，使用专用生图模型
codex Codex CLI AI 辅助编码，支持沙箱策略
web_search Grok API Web 搜索，返回结构化 JSON 结果
web_fetch Grok API 抓取网页内容并转为 Markdown
get_config_info Grok API 显示配置信息并测试 API 连接

工具使用说明

gemini — 执行 Gemini CLI

参数 必填 类型 默认值 描述
PROMPT 是 string — 发送给 Gemini 的任务指令
sandbox 否 bool false 在沙箱模式下运行（隔离执行）
SESSION_ID 否 string — 恢复已有会话，用于多轮对话
return_all_messages 否 bool false 返回所有消息（含推理过程和工具调用）
model 否 string — 模型覆盖。未指定时使用 Gemini CLI 默认值
timeout_secs 否 int 600 超时时间，单位秒（1–3600）

返回结构：

  • success — 执行状态（布尔值）
  • SESSION_ID — 用于恢复对话的唯一标识符
  • agent_messages — 拼接的助手回复文本
  • all_messages — （可选）return_all_messages=true 时返回完整的 JSON 事件
  • error — success=false 时的错误描述

gemini_image — Gemini 图像生成

通过 Gemini API 直接生成图像（非 CLI），支持宽高比和分辨率控制，生成后自动保存到指定目录。

参数 必填 类型 默认值 描述
PROMPT 是 string — 发送给 Gemini 的图像生成指令
model 否 string — 模型覆盖。回退到 GEMINI_IMAGE_MODEL 环境变量
output_dir 否 string — 图片保存目录。回退到 MCP workspace root → 当前工作目录
aspect_ratio 否 string — 宽高比：1:1、2:3、3:2、3:4、4:3、4:5、5:4、9:16、16:9、21:9
image_size 否 string — 分辨率：1K、2K、4K（4K 仅部分模型支持，如 gemini-3-pro-image-preview）
timeout_secs 否 int 600 超时时间，单位秒（1–3600）
sandbox 否 bool false 在沙箱模式下运行
SESSION_ID 否 string — 恢复已有会话
return_all_messages 否 bool false 返回所有消息

返回结构：

  • 生成的图像（base64 内联数据）
  • 模型文本回复（如有）
  • 保存路径信息（文件名格式：gemini_image_YYYYMMDD_HHMMSS.{ext}）

codex — 执行 Codex CLI

参数 必填 类型 默认值 描述
PROMPT 是 string — 发送给 Codex 的任务指令
cd 是 string — 工作目录路径
sandbox 否 string "read-only" 沙箱策略："read-only"、"workspace-write" 或 "danger-full-access"
SESSION_ID 否 string — 恢复之前的会话
skip_git_repo_check 否 bool false 允许在 Git 仓库外运行
return_all_messages 否 bool false 返回完整的推理轨迹
return_all_messages_limit 否 int 10000 return_all_messages 为 true 时的最大消息数
image 否 array [] 要附加的图片文件路径
model 否 string — 覆盖 Codex 模型
yolo 否 bool false 无需确认直接运行，跳过所有沙箱限制
profile 否 string — ~/.codex/config.toml 中的配置文件名
timeout_secs 否 int 600 超时时间，单位秒（最大 3600）
force_stdin 否 bool false 强制通过 stdin 传递 prompt。对于超过 800 字符或包含特殊字符的 prompt 会自动触发

web_search — Grok Web 搜索

参数 必填 类型 默认值 描述
query 是 string — 自然语言搜索查询。可包含主题、时间范围、语言或域名等约束
platform 否 string — 聚焦特定平台（如 "Twitter"、"GitHub"、"Reddit"）
min_results 否 int 3 最少返回结果数
max_results 否 int 10 最多返回结果数
model 否 string — 覆盖 Grok 模型。回退到 GROK_MODEL 环境变量或默认值 grok-4.20-beta

web_fetch — 抓取网页内容

参数 必填 类型 默认值 描述
url 是 string — 有效的 HTTP/HTTPS 网址
model 否 string — 覆盖 Grok 模型。回退到 GROK_MODEL 环境变量或默认值 grok-4.20-beta

get_config_info — 显示 Grok 配置

无参数。返回当前 Grok 配置（API URL、模型、重试设置）并测试 API 连接。API Key 仅从环境变量读取，不会写入配置文件。

安装

方式一：下载预编译二进制（推荐）

从 GitHub Releases 下载对应平台的二进制文件：

平台 文件
Windows x64 ikuncode-aimcp-x86_64-pc-windows-msvc.exe
macOS Apple Silicon ikuncode-aimcp-aarch64-apple-darwin
macOS Intel ikuncode-aimcp-x86_64-apple-darwin
Linux x64 ikuncode-aimcp-x86_64-unknown-linux-gnu

下载后放到 PATH 目录中即可使用。macOS / Linux 需要添加执行权限：

chmod +x ikuncode-aimcp-*
mv ikuncode-aimcp-* /usr/local/bin/ikuncode-aimcp

方式二：npm 安装

npm install -g ikuncode-aimcp

安装时自动从 GitHub Releases 下载预编译二进制。若下载失败则回退到 cargo install（需要 Rust 工具链）。

⚠️ 安装后提示 "Binary not found"？

npm 的 ignore-scripts 设置会阻止 postinstall 脚本执行，导致二进制文件未下载。

检查方法：

npm config list

如果看到 ignore-scripts = true（可能来自环境变量 npm_config_ignore_scripts），需要：

# 方法 1：关闭 ignore-scripts
npm config set ignore-scripts false
# 如果是环境变量设置的，还需要删除环境变量：
# Windows: [System.Environment]::SetEnvironmentVariable("npm_config_ignore_scripts", $null, "User")
# Linux/macOS: 从 ~/.bashrc 或 ~/.zshrc 中移除相关行

# 然后重新安装
npm uninstall -g ikuncode-aimcp
npm install -g ikuncode-aimcp

# 方法 2：保持 ignore-scripts 不变，手动执行安装脚本
node $(npm root -g)/ikuncode-aimcp/scripts/install.js

方式三：cargo 安装

cargo install --git https://github.com/xuxu777xu/ikuncode-aimcp.git

方式四：从源码编译

git clone https://github.com/xuxu777xu/ikuncode-aimcp.git
cd ikuncode-aimcp
cargo build --release
# 二进制文件位于 target/release/ikuncode-aimcp

配置

前置条件

根据你需要的工具，安装对应的 CLI：

  • Gemini CLI — npm install -g @google/gemini-cli 或参见 gemini-cli 文档
  • Codex CLI — npm install -g @openai/codex 或参见 codex 文档
  • Grok Search — 无需安装，只需设置 GROK_API_URL 和 GROK_API_KEY 环境变量

环境变量

Gemini

变量 描述
GEMINI_API_KEY Gemini CLI 的 API 密钥（gemini 工具使用），设置后会覆盖子进程的 GOOGLE_API_KEY
GEMINI_IMAGE_API_KEY 图像生成的 API 密钥（gemini_image 工具使用），可与 GEMINI_API_KEY 不同
GEMINI_API_URL Gemini API 端点 URL（两个工具共用），设置后会覆盖子进程的 GOOGLE_GEMINI_BASE_URL
GEMINI_BIN 覆盖 gemini 二进制文件路径
GEMINI_DEFAULT_TIMEOUT 默认超时时间，单位秒（默认：600）
GEMINI_IMAGE_MODEL 图像生成的默认模型（当 gemini_image 工具未指定 model 时使用）
GEMINI_INCLUDE_DIRS 逗号分隔的额外目录，传给 Gemini CLI 的 --include-directories

Codex

变量 描述
CODEX_BIN 覆盖 codex 二进制文件路径
CODEX_DEFAULT_TIMEOUT 默认超时时间，单位秒（默认：600）
CODEX_ALLOW_DANGEROUS 允许 danger-full-access 沙箱模式（true/false）
CODEX_ALLOW_YOLO 允许 yolo 模式（true/false）
CODEX_ALLOW_SKIP_GIT_CHECK 允许跳过 Git 仓库检查（true/false）

Grok Search

变量 必填 描述
GROK_API_URL 是 Grok API 端点（如 https://api.x.ai/v1）
GROK_API_KEY 是 Grok API 密钥
GROK_MODEL 否 覆盖默认模型（默认：grok-4.20-beta）
GROK_DEBUG 否 启用调试日志（true/false）
GROK_RETRY_MAX_ATTEMPTS 否 最大重试次数（默认：3）
GROK_RETRY_MULTIPLIER 否 退避乘数（默认：1.0）
GROK_RETRY_MAX_WAIT 否 最大重试等待时间，单位秒（默认：10）
GROK_STREAM_TIMEOUT 否 单次 SSE 流响应超时，单位秒（默认：180）
GROK_TOTAL_TIMEOUT 否 含重试的整体操作超时，单位秒（默认：300）
GROK_IDLE_TIMEOUT 否 两个 chunk 之间最大空闲时间，单位秒（默认：30）

MCP 客户端配置

通用配置

{
  "mcpServers": {
    "ikuncode-aimcp": {
      "command": "ikuncode-aimcp",
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key",
        "GEMINI_IMAGE_API_KEY": "your-gemini-image-api-key",
        "GEMINI_API_URL": "base_api",
        "GEMINI_IMAGE_MODEL": "gemini-3-pro-image-preview",
        "GROK_API_URL": "https://api.x.ai/v1",
        "GROK_API_KEY": "base_api",
        "GROK_MODEL": "grok-4.1-fast"
      }
    }
  }
}

启动输出

启动时，ikuncode-aimcp 会将工具检测结果输出到 stderr：

[ikuncode-aimcp] Starting...
[ikuncode-aimcp] Tools detection:
  Gemini:  ✓ (/usr/local/bin/gemini)
  Codex:   ✗ (not found)
  Grok:    ✓ (API key configured)

架构

ikuncode-aimcp/src/
├── main.rs               # 入口：clap + UnifiedServer + AdaptiveStdio
├── lib.rs                # 模块声明
├── server.rs             # UnifiedServer：所有工具 + 运行时可用性检查
├── transport.rs          # AdaptiveStdio（JSONL/LSP 自动检测）
├── detection.rs          # 运行时工具可用性检测
├── shared.rs             # 共享工具（Job Object、超时常量、find_binary）
└── tools/
    ├── mod.rs
    ├── gemini.rs             # Gemini CLI 包装器
    ├── gemini_image_api.rs   # Gemini 图像生成 API（直接 HTTP 调用，支持宽高比/分辨率）
    ├── codex.rs              # Codex CLI 包装器（含安全策略）
    └── grok/
        ├── mod.rs
        ├── config.rs         # 配置单例 + 环境变量 + 超时参数
        ├── prompts.rs        # 搜索/抓取 prompt 常量
        ├── provider.rs       # Grok API 客户端（SSE 流式 + 重试 + 超时检测）
        └── tools.rs          # web_search、web_fetch、get_config_info、switch_model

许可证

GPL-3.0-or-later

About

codex,gemini,gemini image,grok search

Resources

Readme
Activity

Stars

9 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 6

v0.1.5 Latest
Mar 4, 2026
+ 5 releases

Packages

 
 
 

Contributors 1

Languages