# kimi-read-image-mcp

Minimal MCP server for Kimi-compatible image analysis. It exposes exactly one tool, `kimi_read_image`, and sends local images as inline base64 `image_url` parts.

## What It Does

- Exposes one MCP tool: `kimi_read_image`
- Reads a local image file and sends it as an inline base64 `image_url` part
- No provider detection: works with any Kimi-compatible endpoint that accepts `image_url`

## Supported Image Formats

- `image/jpeg` (`.jpg`, `.jpeg`)
- `image/png` (`.png`)
- `image/gif` (`.gif`)
- `image/webp` (`.webp`)
- `image/bmp` (`.bmp`)
- `image/svg+xml` (`.svg`)
- `image/x-icon` (`.ico`)

## Install

Use `npx`:

```bash
npx kimi-read-image-mcp@latest
```

Or install globally:

```bash
npm install -g kimi-read-image-mcp
```

## MCP Setup

### Moonshot example

```json
{
  "mcpServers": {
    "kimi-image": {
      "command": "npx",
      "args": ["-y", "kimi-read-image-mcp@latest"],
      "env": {
        "KIMI_API_KEY": "your-api-key",
        "KIMI_API_BASE_URL": "https://api.moonshot.ai/v1",
        "KIMI_API_MODEL": "kimi-k2.6"
      }
    }
  }
}
```

### Custom endpoint example

```json
{
  "mcpServers": {
    "kimi-image": {
      "command": "npx",
      "args": ["-y", "kimi-read-image-mcp@latest"],
      "env": {
        "KIMI_API_KEY": "your-api-key",
        "KIMI_API_BASE_URL": "https://your-endpoint.example.com/v1",
        "KIMI_API_MODEL": "your-model"
      }
    }
  }
}
```

## Base URL

The server calls the OpenAI-compatible `/chat/completions` endpoint, so `KIMI_API_BASE_URL` must be the base path that contains `/v1`.

- Moonshot: `https://api.moonshot.ai/v1`
- Kimi Coding: `https://api.kimi.com/coding/v1`

If you omit `KIMI_API_BASE_URL`, it defaults to `https://api.moonshot.ai/v1`.

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `KIMI_API_KEY` | Yes | API key for the target endpoint |
| `KIMI_API_BASE_URL` | No | OpenAI-compatible base URL; defaults to `https://api.moonshot.ai/v1` |
| `KIMI_API_MODEL` | No | Model override; defaults to `kimi-k2.6` |

## Tool

### `kimi_read_image`

Analyze a local image file.

Arguments:

- `path`: path to a local image file
- `prompt`: optional instruction such as `Describe this image in one short sentence.`
- `workFolder`: optional working directory for resolving relative paths

## Important Limits

- This project is intentionally minimal and only implements image analysis.
- It does not expose video analysis, web search, shell, file editing, or agent workflows.
- It does not implement OCR fallback or local model inference. If your chosen endpoint or model does not accept the native image flow implemented here, the tool fails fast.

## Development

```bash
npm install
npm run build
npm test
```

Live tests require a local `.env` file:

```bash
KIMI_API_KEY=your-api-key
KIMI_API_BASE_URL=https://api.moonshot.ai/v1
KIMI_API_MODEL=kimi-k2.6
```

Then run:

```bash
npm run test:live
```

`test:live` runs:

- a direct API smoke test for local image analysis
- an SDK stdio MCP round-trip that verifies `tools/list` and `tools/call`

## License

MIT