<div align="center">

# fattly — FATTLY CLI + MCP server

**Turn a product photo into a UGC video ad, generate AI images, video and voiceovers — from your terminal or straight from AI assistants like Claude, Cursor and VS Code via MCP.**

50+ AI models in one account (Veo 3.1, Kling 3, Seedance, Nano Banana, GPT Image, ElevenLabs…) · pay with [fattly.app](https://fattly.app) credits that never expire.

[![npm](https://img.shields.io/npm/v/fattly?color=FF6A4A)](https://www.npmjs.com/package/fattly)
[![CI](https://github.com/industriesfatty-spec/fattly-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/industriesfatty-spec/fattly-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![fattly MCP server](https://glama.ai/mcp/servers/industriesfatty-spec/fattly-mcp/badges/score.svg)](https://glama.ai/mcp/servers/industriesfatty-spec/fattly-mcp)

</div>

---

## MCP (Claude, Cursor, VS Code)

The package is an MCP server — it lets AI assistants generate media through your FATTLY account.

### Option A — Hosted (no install, sign in with OAuth)

Connect your client to the hosted server. No npm, no key to paste — you approve access in the browser.

```
https://fattly.app/api/mcp
```

In Claude: **Settings → Connectors → Add custom connector** → paste the URL. Full setup guide: https://fattly.app/claude-mcp

### Option B — Local (npx, with an API key)

1. On [fattly.app](https://fattly.app) open **Dashboard → API keys** and create a key.
2. Add this to your client's MCP config:

```json
{
  "mcpServers": {
    "fattly": {
      "command": "npx",
      "args": ["-y", "fattly", "mcp"],
      "env": {
        "FATTLY_API_KEY": "gpx_live_YOUR_KEY"
      }
    }
  }
}
```

Installing with an AI agent (Cline, Claude Code, Cursor)? Point it at [llms-install.md](llms-install.md).

### Tools

21 tools — the same set as the hosted server (the local server forwards every call to fattly.app with your key, so new tools appear without updating the package).

| Tool | What it does | Spends credits |
|---|---|---|
| **Ad Studio** | | |
| `fattly_generate_ad_video` | UGC **video ad**: a real-looking AI creator presents your product on camera with a real voice (or hands-only POV / unboxing) | yes (~150) |
| `fattly_generate_ad` | Ad **image** from a product photo: styled product scene or a creator holding it | yes (20) |
| `fattly_create_avatar` | Your own consistent AI creator for ads | yes (20) |
| `fattly_list_ad_presets` | Ad presets, scenes and creator avatars | no (read-only) |
| **Images** | | |
| `fattly_generate_image` | Text-to-image and image editing (multi-image edits) | yes |
| `fattly_upscale` | Upscale an image | yes |
| `fattly_remove_background` | Clean cutout without background | yes |
| `fattly_inpaint` | Repaint a masked area to match a prompt | yes |
| `fattly_face_swap` | Swap a face (SFW, only faces you have the right to use) | yes |
| **Video** | | |
| `fattly_generate_video` | Text-to-video and image-to-video (Veo, Kling, Seedance…) | yes |
| `fattly_video_status` | Check a video that is still rendering | no (read-only) |
| `fattly_animate_photo` | Bring a still photo to life | yes |
| `fattly_trend_video` | Trend-style video from a photo and a preset | yes |
| `fattly_edit_video` | Draw-to-Edit: change a masked region of a video with text | yes |
| `fattly_actor_swap` | Replace the creator in an existing video | yes |
| **Audio** | | |
| `fattly_generate_audio` | Voiceover (text-to-speech) or music | yes |
| `fattly_clone_voice` | Clone a voice (with consent) or reuse a saved one | yes |
| `fattly_transcribe` | Audio → text with timed segments | yes |
| **Account** | | |
| `fattly_credits` | Current credit balance | no (read-only) |
| `fattly_list_models` | Models and their price in credits | no (read-only) |
| `fattly_upload_image` | Photo (URL, base64 or local file) → URL for edit / ad / image-to-video tools | no |

Every tool carries MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`), so clients can ask before paid calls. Failed generations are refunded automatically. Content must be safe-for-work.

## CLI

```bash
npm install -g fattly   # Node.js 18+
fattly login            # paste your gpx_live_… key
```

```bash
fattly credits
fattly models video

fattly generate "astronaut cat on Mars" --model nano-banana-2 --out cat.png
fattly video "ocean waves at sunset" --model kling-3-standard --out waves.mp4
fattly audio "Welcome to FATTLY" --voice Rachel --out voice.mp3
fattly audio "calm ambient" --music --seconds 30 --out music.mp3
```

## Configuration

| Variable | Purpose |
|---|---|
| `FATTLY_API_KEY` | API key (alternative to `fattly login`) |
| `FATTLY_API_URL` | API address override (default `https://fattly.app`) |

The key saved by `fattly login` lives in `~/.fattly/config.json` with owner-only permissions.

## More

- Website: https://fattly.app
- Even more in the web app: AI dubbing with lip-sync in 5 languages, virtual try-on, Cinema Studio.
- Issues: https://github.com/industriesfatty-spec/fattly-mcp/issues

MIT © Fattly