# KieAI MCP — KI-Mediengeneration via kie.ai

> MCP-Server für KI-gestützte Mediengeneration: Bilder, Videos, Audio und Upscaling mit 99 KI-Modellen — lokal via Claude Code oder remote via Docker/Coolify.

## Features

- **99 KI-Modelle** — Bilder, Videos, Audio, Upscaling
- **Zwei Transport-Modi** — stdio (lokal) und HTTP/SSE (remote)
- **YAML-basierte Modellkonfiguration** — neue Modelle ohne Code hinzufügen
- **Automatisches Polling** — wartet auf Ergebnisse asynchroner Generierungen
- **Docker-ready** — einfaches Deployment via Docker oder Coolify

## Quick Start

### Lokal (stdio) — Als Claude Code Plugin

```bash
# Plugin installieren
claude mcp add kie-ai-mcp -- bun run /pfad/zu/kie-ai-plugin/src/index.ts

# API Key setzen
export KIE_API_KEY="dein-kie-ai-api-key"
```

### Remote (HTTP/SSE) — Docker Deployment

```bash
# Image bauen
docker build -t kie-ai-mcp .

# Container starten
docker run -e KIE_API_KEY=dein-key -e MCP_TRANSPORT=http -p 3001:3001 kie-ai-mcp

# Health Check
curl http://localhost:3001/health
```

## Konfiguration

1. Account auf [kie.ai](https://kie.ai) erstellen
2. API Key generieren unter https://kie.ai/api-key
3. Key als Umgebungsvariable setzen:

```bash
export KIE_API_KEY="dein-kie-ai-api-key"
```

| Variable | Beschreibung | Default |
|----------|-------------|---------|
| `KIE_API_KEY` | API Key von kie.ai | — (Pflicht) |
| `MCP_TRANSPORT` | Transport-Modus: `stdio` oder `http` | `stdio` |
| `PORT` | Port für HTTP/SSE-Modus | `3001` |

## Verfügbare Modelle

### Bilder (7 Modelle)

| Modell | Stärke | Kosten |
|--------|---------|--------|
| **Flux 2 Pro** | Allrounder, bis 2K | ~$0.03 |
| **Seedream 3.0** | Text-Rendering | ~$0.02 |
| **Google Imagen 4** | Negative Prompts | ~$0.04 |
| **Ideogram Character** | Referenz-Bilder | ~$0.05 |
| **Qwen** | Viele Parameter | ~$0.02 |
| **Grok Imagine** | Kreativ (nur EN) | ~$0.03 |
| **Z-Image** | Fotorealistisch | ~$0.01 |

### Videos (6 Modelle)

| Modell | Typ | Max Dauer | Kosten |
|--------|-----|-----------|--------|
| **Sora 2 Pro** | Text-to-Video | 15s | ~$2.00 |
| **ByteDance V1** | Text-to-Video | 10s | ~$0.40 |
| **Grok Video** | Text-to-Video | 15s | ~$0.50 |
| **Kling V2.1** | Image-to-Video | 10s | ~$0.30 |
| **Wan 2.6** | Image-to-Video | 15s | ~$0.35 |
| **Hailuo 2.3** | Image-to-Video | 10s | ~$0.40 |

### Audio (1 Modell)

| Modell | Typ | Kosten |
|--------|-----|--------|
| **ElevenLabs TTS** | Text-to-Speech | ~$0.01 |

### Upscaling (2 Modelle)

| Modell | Max Faktor | Kosten |
|--------|------------|--------|
| **Topaz** | 8x | ~$0.05 |
| **Recraft Crisp** | Auto | ~$0.03 |

## Transport-Modi

### stdio (Standard)

Für die lokale Integration mit Claude Code. Der MCP-Server kommuniziert über stdin/stdout direkt mit Claude Code. Generierte Dateien werden lokal gespeichert.

```bash
# Automatisch bei Plugin-Nutzung via Claude Code
claude mcp add kie-ai-mcp -- bun run /pfad/zu/kie-ai-plugin/src/index.ts
```

### HTTP/SSE (Remote)

Für Remote-Nutzung via Docker oder Coolify. Der Server stellt einen HTTP-Endpoint mit Server-Sent Events bereit.

**Wichtig:** Im HTTP-Modus werden nur Result-URLs zurückgegeben — es findet kein lokaler File-Download statt.

```bash
MCP_TRANSPORT=http PORT=3001 bun run src/index.ts
```

## Docker

### Image bauen

```bash
docker build -t kie-ai-mcp .
```

### Container starten

```bash
docker run \
  -e KIE_API_KEY=dein-api-key \
  -e MCP_TRANSPORT=http \
  -p 3001:3001 \
  kie-ai-mcp
```

### Health Check

```bash
curl http://localhost:3001/health
```

## Coolify Deployment

1. **GitHub Repo verbinden** — Repository in Coolify als neue Ressource hinzufügen
2. **Umgebungsvariablen setzen:**
   - `KIE_API_KEY` — Dein kie.ai API Key
   - `MCP_TRANSPORT` — auf `http` setzen
   - `PORT` — `3001` (oder nach Bedarf)
3. **Domain zuweisen** — Über die Coolify-Oberfläche eine Domain konfigurieren (z.B. `kie-mcp.deine-domain.de`)
4. **Deployen** — Build starten, Coolify nutzt automatisch das Dockerfile

## Remote MCP Client Konfiguration

Um einen MCP-Client mit dem remote deployten Server zu verbinden:

```json
{
  "mcpServers": {
    "kie-ai-mcp": {
      "url": "https://kie-mcp.deine-domain.de/sse"
    }
  }
}
```

## Nutzung

### Bilder erstellen
```
"Erstelle ein Bild von einem Sonnenuntergang am Meer"
"Generiere ein fotorealistisches Portrait mit Flux 2"
"Mach ein Bild mit Text 'Hello World' — nutze Seedream"
```

### Videos erstellen
```
"Erstelle ein Video von tanzenden Katzen"
"Animiere dieses Bild [URL] mit Kling"
"Generiere ein 10-Sekunden Video eines Wasserfalls"
```

### Audio erstellen
```
"Lies diesen Text vor: Willkommen bei Alice"
"Text to Speech auf Deutsch: Guten Morgen Oliver"
```

### Bilder hochskalieren
```
"Skaliere dieses Bild hoch: [URL]"
"Upscale mit 4x Faktor"
```

## Neues Modell hinzufügen

1. YAML-Datei in `models/{type}/` erstellen
2. Fertig — kein Code nötig

## Entwicklung

```bash
bun install        # Dependencies
bun test           # Tests (61 Tests)
bun run build      # TypeScript kompilieren
bun run dev        # Watch Mode
```

## Lizenz

MIT