# Kimi Vision MCP Server

MCP server for **Kimi** (Moonshot AI) vision models — analyze images through
the OpenAI-compatible `/chat/completions` endpoint at
`https://api.moonshot.cn/v1`.

## Features

- 🖼️ Analyze images (local files: png/jpg/jpeg/gif/webp)
- 🧠 Auto-pick strongest **thinking mode** per model:
  - `kimi-k3` → `reasoning_effort: "max"`
  - `kimi-k2.6` / `kimi-k2.5` / `kimi-k2.7-code` → `thinking: {type: "enabled"}`
- 📏 Up to **1M token context** (kimi-k3)
- 💰 Same billing as Moonshot V1 — see [pricing](https://platform.moonshot.cn/docs/pricing/chat)
- ⚡ One-line `npx` deploy, zero non-MCP dependencies

## Requirements

- Node.js >= 18
- A [platform.kimi.com](https://platform.kimi.com) API key

## Install & run

```bash
cd kimi-vision-mcp-server
npm install
npm start
```

## Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `KIMI_API_KEY` | ✅ | — | Your Kimi/Moonshot API key. (`MOONSHOT_API_KEY` also accepted.) |
| `KIMI_MODEL` | | `kimi-k3` | Model name. Vision-capable: `kimi-k3`, `kimi-k2.7-code`, `kimi-k2.6`, `kimi-k2.5`, `moonshot-v1-*-vision-preview`. |
| `KIMI_BASE_URL` | | `https://api.moonshot.cn/v1` | Override endpoint (for proxies). |
| `KIMI_MAX_TOKENS` | | `4096` | Default max output tokens. |

## Claude Code / CC-Switch config

```json
{
  "mcpServers": {
    "kimi-vision": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kimi-vision-mcp-server"],
      "env": {
        "KIMI_API_KEY": "your-kimi-api-key",
        "KIMI_MODEL": "kimi-k3"
      }
    }
  }
}
```

Or run from a local checkout:

```json
{
  "mcpServers": {
    "kimi-vision": {
      "command": "node",
      "args": ["D:\\GitHub\\Claude\\MCP\\Kimi\\kimi-vision-mcp-server\\src\\index.js"],
      "env": {
        "KIMI_API_KEY": "your-key-here"
      }
    }
  }
}
```

## Tool: `kimi_vision_understand`

| Parameter | Type | Required | Description |
|---|---|---|---|
| `image` | string | ✅ | Local image file path (`C:/path/to/x.png`) or `ms://<file-id>` for pre-uploaded. **Remote HTTP URLs NOT supported.** |
| `prompt` | string | ✅ | What to ask about the image. |
| `detail` | enum | | `auto` / `low` / `high`. Default `auto`. |
| `max_tokens` | number | | Max output tokens. Default 4096. |
| `thinking` | bool | | Enable reasoning. Default `false`. Auto-mapped per model. |

## Important: Remote URLs not supported

Kimi's vision API does **not** accept remote HTTP image URLs (per the
[official docs](https://platform.moonshot.cn/docs/guide/use-kimi-vision-model#功能支持与限制)).
You must either:
- Pass a **local file path** (the MCP will inline it as base64), or
- Upload to Moonshot first and pass `ms://<file-id>` (advanced).

Remote URLs are rejected with a clear error message.

## Why no `temperature` parameter?

Per the [Kimi API model params reference](https://platform.moonshot.cn/docs/api/models-overview),
all current Kimi models have **fixed** temperature:

| Model | Temperature |
|---|---|
| `kimi-k3` | fixed 1.0 |
| `kimi-k2.7-code` (and -highspeed) | fixed 1.0 |
| `kimi-k2.6` thinking | fixed 1.0 |
| `kimi-k2.6` non-thinking | fixed 0.6 |
| `kimi-k2.5` thinking | fixed 1.0 |
| `kimi-k2.5` non-thinking | fixed 0.6 |

Passing any other value returns HTTP 400. Moonshot has already tuned each
model to its optimal temperature, so this MCP deliberately omits the parameter
and lets the API use its built-in default. Use the `thinking` flag to switch
between the 1.0 / 0.6 modes for K2.6 / K2.5.

## Why Kimi for vision?

- **Longest context**: kimi-k3 ships with 1M tokens — useful for analyzing
  long documents alongside images.
- **Strong Chinese & English OCR**.
- **Native video understanding** on kimi-k3 / kimi-k2.7-code / kimi-k2.6 (not
  exposed by this MCP yet — file upload only).
- **Cost-effective**: ¥2/M output for the flagship.

## Related projects

- [doubao-vision-mcp-server](https://github.com/kira4094/doubao-vision-mcp-server) — ByteDance Doubao vision
- [glm-vision-mcp-server](https://github.com/kira4094/glm-vision-mcp-server) — Zhipu GLM-5V-Turbo
- [qwen-vision-mcp-server](https://github.com/kira4094/qwen-vision-mcp-server) — Alibaba Qwen3.7-plus
- [@kira4094/agnes-image-mcp-server](https://www.npmjs.com/package/@kira4094/agnes-image-mcp-server) — Agnes Image (text-to-image)

## License

MIT