Metadata-Version: 2.5
Name: mostai-mcp
Version: 0.5.0
Summary: MCP server for MostAI (most-ai.com): generate images, video, music, speech and text with 60+ models from Claude Code, Claude Desktop or any MCP client
Project-URL: Homepage, https://most-ai.com
Project-URL: Repository, https://github.com/most-ai-com/mostai-mcp
Project-URL: Issues, https://github.com/most-ai-com/mostai-mcp/issues
Project-URL: Changelog, https://github.com/most-ai-com/mostai-mcp/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/most-ai-com/mostai-mcp#readme
Author-email: MostAI <contact@most-ai.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,claude,claude-code,claude-desktop,image-generation,mcp,mcp-server,model-context-protocol,mostai,music-generation,text-to-speech,video-generation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Multimedia :: Video
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25
Requires-Dist: mcp[cli]<2,>=1.2.0
Provides-Extra: login
Requires-Dist: playwright>=1.40; extra == 'login'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.most-ai-com/mostai-mcp -->

# mostai-mcp

Generate images, video, music, speech and text with 60 models through your **MostAI**
account — from Claude Code, Claude Desktop or any MCP client.

[![CI](https://github.com/most-ai-com/mostai-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/most-ai-com/mostai-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/mostai-mcp)](https://pypi.org/project/mostai-mcp/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/most-ai-com/mostai-mcp/blob/main/LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)

Русская версия → [README.ru.md](https://github.com/most-ai-com/mostai-mcp/blob/main/README.ru.md)

## What it is

`mostai-mcp` is an MCP server that connects Claude to your own [MostAI](https://most-ai.com)
account. You sign in once with Google; after that Claude can pick a model, price a job,
generate, look at the result and save the file for you. Generations spend your real MostAI
balance (₽) — with free quota used automatically wherever it exists.

- **Images** — text-to-image and image-to-image edits (up to 14 reference pictures).
- **Video** — text-to-video, animate a still photo, first/last-frame control, Russian
  voice-over on some models.
- **Music, speech and text** — songs from lyrics, expressive TTS, multi-speaker dialogue,
  and chat models including a free unlimited one.
- **Ready-made apps** (no prompt, just files): face swap, background removal, photo and
  video upscaling, photo restoration, live photo, lip-sync a portrait to a voice, a
  trending dance from a single photo, and raster → SVG vectorization.

The catalogue is read **live from the API** at every call, so new models appear without
updating this package — 60 live models in the 2026-09-03 snapshot.

## Install

### 1. One command (Claude Code, any OS) — recommended

Prerequisites: [uv](https://docs.astral.sh/uv/), Google Chrome, a MostAI account.

```bash
# 1. Install uv if you don't have it — Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# ... or macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Install and set up the server
uv tool install "mostai-mcp[login]"
mostai-mcp setup
```

The `[login]` extra pulls in Playwright, used **only** by the one-time `mostai-login`
sign-in window; without it the server runs but cannot open a sign-in browser.

`mostai-mcp setup` does the whole install in one pass: registers the `mostai` server with
Claude Code at **user scope** (`claude mcp add mostai -s user -- …`), installs the usage
skill into `~/.claude/skills/mostai/SKILL.md`, seeds `~/.mostai-mcp/.env` with safe spend
limits, opens the sign-in window (skipped if you are already signed in), then prints your
balance, free quota and the first thing to try. Flags: `--no-login`, `--skip-claude`,
`--print-desktop-config`, `--config-dir PATH` (override `CLAUDE_CONFIG_DIR` / `~/.claude`).

Until the package is published on PyPI, install from git instead (same thing, the
`--with playwright` flag stands in for the `[login]` extra):

```bash
uv tool install --with playwright git+https://github.com/most-ai-com/mostai-mcp
mostai-mcp setup
```

### 2. Windows without a terminal

1. Open the [repository](https://github.com/most-ai-com/mostai-mcp), choose
   **Code ▾ → Download ZIP**, and unzip it anywhere.
2. Close Claude Code (while it runs it locks the installed executable).
3. Double-click **`install.cmd`** — it installs `uv` if missing, installs the tool
   globally, and opens Chrome for the one-time sign-in. Then restart Claude Code.

The folder can be deleted afterwards — the tool is installed globally. To update later,
download a fresh ZIP and double-click `install.cmd` again.

### 3. Claude Desktop

Install as above, then run `mostai-mcp setup --skip-claude --print-desktop-config`.
It prints the path of your `claude_desktop_config.json` — `%APPDATA%\Claude\` on
Windows, `~/Library/Application Support/Claude/` on macOS, `~/.config/Claude/` on Linux —
and the block to paste into it:

```json
{ "mcpServers": { "mostai": { "command": "/full/path/to/mostai-mcp" } } }
```

`--skip-claude` skips the Claude Code CLI registration, which is pointless if you only use
Desktop. Restart Claude Desktop after editing the file.

### First touch

Restart Claude Code (or Desktop) and say: *"Generate an image of a red bicycle on a beach
with MostAI"*. The first Nano Banana 2 images are **free** — free quota per model is
reported by `get_balance().free_generations` and `list_free_generations()`, and the tools
use it automatically.

## Signing in

Sign-in happens in a **separate Chrome window**, not your normal one. That is not a
preference: modern Chrome (App-Bound Encryption, verified against Chrome 152 on
2026-09-03) encrypts its cookie store so no other program can read it, and holds the
`Cookies` file open exclusively while it runs, so it cannot even be copied. So
`mostai-login` opens its own Chrome profile (`~/.mostai-mcp/pw-profile/`) where you click
**Sign in with Google** once. The profile persists — later refreshes need no re-login,
and your everyday Chrome can stay open.

The cookie is read from, in order: the `MOSTAI_COOKIE` environment variable (for
headless/CI use), the **system keyring** (Windows Credential Manager / macOS Keychain /
Linux SecretService, service `mostai-mcp`) — the normal case — and `~/.mostai-mcp/.env`,
a plain-text fallback for environments with no working keyring. Check status without
opening a browser with `mostai-login --check`.

If a tool returns **401 / session expired**, run `mostai-login` again (Windows, no
terminal: double-click `install.cmd`). The running server re-reads the cookie from the
keyring on an auth error and retries once, so **no server restart is needed** — which
matters for long-lived processes like Claude Desktop.

## Tools

22 tools. Their docstrings in `mostai_mcp/server.py` are the authoritative reference —
that is what your MCP client actually reads.

| Tool | What it does |
|---|---|
| **Catalogue** | |
| `list_models(type?, sort_by_price?, include_deprecated?)` | Live catalogue with price, `free_left`, `capabilities` (`image:edit`, `video:first_last_frame`, `low_moderation`, …), accepted inputs, `no_prompt`, `credits_per_message`. Retired models hidden by default |
| `describe_model(model_id)` | One model's exact `parameters` and options, attachment slots, voices, dance presets, price and a copyable `example_call` |
| **Account** | |
| `get_balance()` | Balance in ₽, low-balance alert, and free generations per model |
| `spending_status()` | Balance plus the configured spend guards |
| `whoami()` | Email, message credits, permissions |
| `list_free_generations()` | Remaining free runs per model (`-1` = unlimited) |
| `estimate_price(model, prompt?, aspect_ratio?, duration?, quality?, parameters?)` | Price a job in ₽ **without running it**; invalid values are refused here |
| **Text** | |
| `chat(prompt, model?, system?, session?, images?)` | Text reply. Spends message credits, not ₽. Default `chatgpt-free` is free and unlimited |
| **Images** | |
| `generate_image(prompt, model?, aspect_ratio?, quality?, images?, …)` | Text-to-image; `images` = references. Default `google/nano-banana-2` |
| `edit_image(prompt, source, model?, …)` | Image-to-image: transform an existing picture (URL or local path, or a list) |
| **Video** | |
| `generate_video(prompt, model?, duration?, quality?, mode?, images?, videos?, audios?, …)` | Text-to-video. Default `xai/grok-imagine-video`. `mode`: `reference` or `frames` |
| `animate_image(prompt, source, model?, mode?, …)` | Animate a still photo; `prompt` describes the motion; `mode="frames"` (where the model offers it) makes two pictures the first and last frame |
| **Audio** | |
| `generate_audio(text, model?, voice?, style?, dialogue?, …)` | Speech (`elevenlabs/v3`, `google/gemini-3.1-flash-tts`), multi-speaker dialogue, or music (`suno`: `text` = lyrics, `style` = genre) |
| **Any model** | |
| `generate_media(model, prompt?, images?, videos?, audios?, named_images?, preset?, parameters?, …)` | Call **any** model in the catalogue, including the prompt-less apps |
| **Files & gallery** | |
| `media_status(public_id)` | Poll an async generation |
| `download_media(url, dest_path?)` | Save the binary to disk (default `~/.mostai-mcp/downloads`) |
| `preview_media(url_or_public_id)` | Show the image inline so Claude can judge it (video: its thumbnail) |
| `list_gallery(limit?, success_only?, tag?, public?)` | Your gallery, or the public explore feed |
| **Lifecycle** | |
| `share_link(public_id)` | Public share URL — `https://most-ai.com/s/{public_id}` |
| `publish_media(item_id, published?)` | Publish or unpublish to the public gallery |
| `like_media(item_id)` | Like a generation |
| `delete_media(item_id)` | Permanently delete one of your generations (irreversible) |

Every generator also accepts `save_path`, `max_price`, `confirm` and `wait`; all of them
except `generate_audio` also accept `free_mode` (audio has no free tier).

## What you can ask for

| Say this | What runs |
|---|---|
| "Generate an image of a red bicycle on a beach" | `generate_image` → `google/nano-banana-2` (free quota) |
| "Make this photo look like a watercolour painting" | `edit_image(source=…)` |
| "Turn this photo into a 5-second video" | `animate_image` → `xai/grok-imagine-video` |
| "Cut out the background of this picture" | `generate_media("background-remover-v1", images=[…])` |
| "Put my face on this portrait" | `generate_media("faceswap", named_images={"swap_image": …, "input_image": …})` |
| "Upscale this photo 4×" | `generate_media("prunaai/p-image-upscale", images=[photo], parameters={"factor": "x4"})` |
| "Make this portrait say this line" | `generate_media("kling/ai-avatar", images=[photo], audios=[voice])` |
| "Make a dancing video from this photo" | `generate_media("kwaivgi/kling-v2.6-motion-control", images=[photo], preset="…")` |
| "Read this text in a warm female voice" | `generate_audio` → `elevenlabs/v3` |
| "Write me a song about autumn in Yekaterinburg" | `generate_audio` → `suno` (`text` = lyrics, `style` = genre) |
| "How much would a 10-second clip on Kling 3.0 cost?" | `estimate_price` — no money spent |

## Money & safety

- **Free first.** `free_mode=None` (the default) runs for free whenever the model still
  has free quota and you did not pin a paid `quality`/`duration`; the result reports
  `free_mode`, `free_locked` and `free_left_after`. `True` forces free, `False` always pays.
- **A price gate, not a block.** A generation costing **≥ `MOSTAI_WARN_PRICE`** (default
  50₽) returns `needs_confirmation` with the price and charges nothing; it runs only when
  the call is repeated with `confirm=True`. Set `MOSTAI_WARN_PRICE=0` to turn the gate off.
- **`MOSTAI_MAX_PRICE`** is an optional absolute hard cap (unset by default) — anything
  above it is refused outright; `MOSTAI_MIN_BALANCE` (default 50₽) drives the low-balance
  alert; per-call `max_price=` caps a single generation.
- **Validation before money.** Parameters, attachment counts and required slots are checked
  against the live catalogue before a byte is uploaded, so a wrong value comes back as an
  error listing what's allowed — not as a charged failure.
- **Two currencies.** Media spends ₽; `chat` spends **message credits**
  (`whoami().message_credits`, `credits_per_message` in `list_models(type='text')`) — a
  text model showing `price_rub: 0` is not free.
- **Paths are not sandboxed.** `save_path` / `dest_path` write wherever the agent asks —
  the server does not restrict paths, so keep untrusted content out of the prompt.
- **Where to see a price:** `estimate_price(model, …)` with the parameters you actually
  intend to use, or `list_models`. `price_from: true` means the listed price is the
  cheapest tier ("from") — longer or higher-quality jobs cost more.

Orientation only, from the 2026-09-03 catalogue snapshot: images ≈ 3–26₽ (the popular ones
≈ 3–10₽), the prompt-less AI apps ≈ 3–26₽, TTS ≈ 4₽, a song ≈ 20₽, prompted video
≈ 14–66₽ plus a per-second charge. Always check the live price before spending.

## Updating

```bash
uv tool upgrade mostai-mcp
```

From a git clone: run `./update.ps1` (Windows) or `bash update.sh` (macOS/Linux) in the
folder — it pulls, reinstalls and refreshes the skill; your login is kept. From a ZIP:
download a fresh one and double-click `install.cmd`. **Close Claude Code before updating** — while it runs it locks the installed executable
and the reinstall fails. Restart it afterwards. `get_balance()` and `whoami()` add an
`update_available` line when a newer release is out (checked at most once a day).

## Where things live

Everything lives in `~/.mostai-mcp` (override with the `MOSTAI_HOME` env var): `.env`
(spend limits, and the cookie only as a keyring fallback), `pw-profile/` (the dedicated
Chrome profile used for sign-in), `downloads/` (default destination of `download_media`
and `save_path`), `version_check.json` (cache of the daily update check). The session
cookie itself lives in the system keyring under the service name `mostai-mcp`.

## Troubleshooting

- **401 / 403 / "session expired"** — the cookie expired. Run `mostai-login` (Windows, no
  terminal: double-click `install.cmd`). No server restart needed.
- **"not enough message credits"** — `chat` on a paid text model with no credits left.
  Check `whoami().message_credits`, top up, or switch to `chatgpt-free`.
- **`failed: true` with `alternatives`** — the model refused or errored (moderation is the
  usual cause). Rephrase, or try one of the listed alternative models.
- **`needs_confirmation` in the result** — the job costs ≥ `MOSTAI_WARN_PRICE`. Nothing
  was charged; repeat the call with `confirm=True` to proceed.
- **"Model … is not in the catalogue"** — the id is wrong or the model was retired. Run
  `list_models()` for current ids; `include_deprecated=True` shows retired ones.
- **Windows: "uv is not recognized"** right after installing uv — restart the terminal, or
  run `uv tool update-shell` and restart it.
- **`claude` CLI not found** — setup prints the manual step; once the CLI is installed run
  `claude mcp add mostai -s user -- /full/path/to/mostai-mcp` yourself.

## How it works / for developers

`mostai-mcp` is an **unofficial connector** to the private app API behind
`chatbot.most-ai.com`. It authenticates with your browser session cookie and speaks to:

| Endpoint | Used for |
|---|---|
| `GET /api/v1/models-v2` | The live model catalogue (readable without auth) |
| `POST /api/v1/attachments` | Upload input files up front (free); the body then references them by uuid |
| `POST /api/v1/images/price` | Price a job (pure JSON body) |
| `POST /api/v1/images/generate` | Start a generation (multipart with a `json` field) |
| `GET /api/v1/images/shared/{public_id}` | Poll the result |
| `POST /api/v1/chat` | Text, streamed over SSE |

The **catalogue is the source of truth**: parameters, attachment slots, prompt-vs-app
expectations and prices are normalized from `models-v2` and validated against it before a
request is sent, so there is no hardcoded model list to go stale.

```bash
git clone https://github.com/most-ai-com/mostai-mcp.git && cd mostai-mcp
uv sync
uv run pytest -q          # unit tests, network-free
uv run ruff check .
uv run pytest -m live     # read-only smoke against the real API (needs your cookie, 0₽)
```

See [CONTRIBUTING.md](https://github.com/most-ai-com/mostai-mcp/blob/main/CONTRIBUTING.md), [SECURITY.md](https://github.com/most-ai-com/mostai-mcp/blob/main/SECURITY.md) and
[CHANGELOG.md](https://github.com/most-ai-com/mostai-mcp/blob/main/CHANGELOG.md). Licensed under the [MIT License](https://github.com/most-ai-com/mostai-mcp/blob/main/LICENSE), © 2026 MostAI.
MCP registry name: `io.github.most-ai-com/mostai-mcp`.

---

**Disclaimer.** This is an unofficial connector to a private API that is not a public,
versioned contract — endpoints and fields can change without notice if MostAI updates the
app. Model names and descriptions come from the MostAI catalogue and are in Russian, the
way the site itself presents them.
