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.

Русская версия → README.ru.md

What it is

mostai-mcp is an MCP server that connects Claude to your own MostAI 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, Google Chrome, a MostAI account.

# 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):

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, 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:

{ "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.

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

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

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:

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.

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, SECURITY.md and CHANGELOG.md. Licensed under the MIT 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.