# Kimi Code + MiniMax Web Search MCP Server

让本地 Kimi Code 调用 MiniMax 原生的 `web_search` Server Tool 实现联网搜索。

## 背景

Kimi Code 内置的 `WebSearch` 工具只能接 Moonshot/Kimi 的搜索服务（`services.moonshot_search`），无法直接复用 MiniMax 的模型侧搜索能力。MiniMax 的 `web_search` 是一个 **Server Tool**，只有直接调用 MiniMax 的 Anthropic Messages API 并传入 `tools: [{"type": "web_search_20250305", "name": "web_search"}]` 时才会触发。

本项目作为一个 **MCP Server**，把 MiniMax 的联网搜索能力桥接到 Kimi Code，让 Agent 可以通过 `mcp__minimax-web-search__web_search` 工具进行搜索。

## 目录结构

```
kimi-minimax-websearch-mcp/
├── minimax_web_search.py   # MCP Server 主脚本
├── requirements.txt        # Python 依赖
├── mcp.json.example        # Kimi Code MCP 配置示例
├── .gitignore              # 忽略 venv 和 minimax_key
└── README.md               # 本文件
```

## 前置条件

- Python 3.10+
- 一个有效的 MiniMax API key
- 已安装并配置好 Kimi Code CLI

## 安装步骤

### 1. 克隆/复制本文件夹到目标电脑

例如放到：

```bash
~/tools/kimi-minimax-websearch-mcp
```

### 2. 创建虚拟环境并安装依赖

```bash
cd ~/tools/kimi-minimax-websearch-mcp
python -m venv .venv
.venv/bin/pip install -r requirements.txt
```

> Windows 上 Python 路径为 `.venv\\Scripts\\python.exe`。

### 3. 放入 MiniMax API Key

在本文件夹根目录创建一个 `minimax_key` 文件，把 key 放进去（不要引号、不要空行）：

```bash
echo 'sk-你的-minimax-key' > minimax_key
```

或者设置环境变量：

```bash
export MINIMAX_API_KEY='sk-你的-minimax-key'
```

脚本会按以下优先级读取：

1. `MINIMAX_API_KEY` 环境变量
2. 本文件夹下的 `minimax_key` 文件
3. 运行时的当前工作目录下的 `minimax_key` 文件

`minimax_key` 已被 `.gitignore` 忽略，不会误提交。

### 4. 配置 Kimi Code

把 `mcp.json.example` 复制为 `~/.kimi-code/mcp.json`（如果已有该文件，则合并 `mcpServers` 部分），并把里面的路径改成你本机的绝对路径。

```json
{
  "mcpServers": {
    "minimax-web-search": {
      "command": "/Users/你的用户名/tools/kimi-minimax-websearch-mcp/.venv/bin/python",
      "args": [
        "/Users/你的用户名/tools/kimi-minimax-websearch-mcp/minimax_web_search.py"
      ],
      "cwd": "/Users/你的用户名/tools/kimi-minimax-websearch-mcp",
      "env": {
        "MINIMAX_MODEL": "MiniMax-M3"
      }
    }
  }
}
```

参数说明：

- `command`：虚拟环境中的 Python 解释器绝对路径。
- `args`：MCP Server 脚本的绝对路径。
- `cwd`：本文件夹的绝对路径，确保 `minimax_key` 能被找到。
- `env.MINIMAX_MODEL`：触发搜索时使用的 MiniMax 模型，默认 `MiniMax-M3`，可改为 `MiniMax-M2.5` 等。

### 5. 添加权限规则（可选但推荐）

在 `~/.kimi-code/config.toml` 末尾追加：

```toml
[[permission.rules]]
decision = "allow"
pattern = "mcp__minimax-web-search__*"
scope = "user"
reason = "Allow MiniMax native web search MCP tool"
```

这样每次搜索不会弹 approval 确认。

### 6. 重启 Kimi Code

MCP Server 只在 Kimi Code 启动时加载。退出并重新进入 TUI，或在 TUI 里执行：

```text
/reload
```

然后执行：

```text
/mcp
```

应能看到 `minimax-web-search` 已连接，工具列表里有 `web_search`。

## 使用

在 Kimi Code 中直接问需要联网的问题即可，例如：

```text
今天有什么科技新闻？
```

Agent 会自动调用 `mcp__minimax-web-search__web_search`，返回答案和来源。

## 故障排查

### /mcp 里看不到 minimax-web-search

1. 确认 `~/.kimi-code/mcp.json` 路径是否正确且为绝对路径。
2. 确认 `minimax_key` 存在且有效。
3. 在终端手动运行：

   ```bash
   /你的路径/.venv/bin/python /你的路径/minimax_web_search.py
   ```

   如果没有报错并显示 FastMCP 启动信息，说明脚本本身正常。

### 调用搜索时报 401/403

- 检查 `minimax_key` 是否有效、是否有多余空格或换行。
- 检查该 key 是否有权限调用 MiniMax Anthropic Messages API。

### 搜索没有返回结果

- MiniMax 的 `web_search` 是模型自主决定的 Server Tool，某些问题可能不会触发搜索。换更明确的查询词再试。
- 检查 `env.MINIMAX_MODEL` 是否填写正确。

## 迁移到另一台电脑

1. 复制整个 `kimi-minimax-websearch-mcp` 文件夹。
2. 在新电脑上执行「安装步骤」的 2~5 步。
3. 重启 Kimi Code。

## 许可证

按项目现有约定使用。