# genspark-mcp

[![CI](https://github.com/stockvalue/genspark-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/stockvalue/genspark-mcp/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/stockvalue/genspark-mcp)](https://github.com/stockvalue/genspark-mcp/releases)
[![License](https://img.shields.io/github/license/stockvalue/genspark-mcp)](LICENSE)

Use Genspark image and video generation from Claude Code, Codex CLI, or any
stdio-compatible MCP client — locally, with your own Genspark account.

`genspark-mcp` exposes two local MCP servers:

- `genspark-image-mcp` — text-to-image and reference-image generation, with
  `GPT Image 2` as the default model.
- `genspark-video-mcp` — text-to-video and image-to-video generation through
  Genspark's video UI.

The browser stays on the user's Mac. There is no hosted API, shared cookie
pool, shared account, or server-side credential store.

> Unofficial community project. It is not affiliated with or endorsed by
> Genspark. Genspark's UI, plans, and access policies can change.

## The short version

After installing and logging in once, ask a coding agent to call the MCP:

```text
Create a 16:9 product hero image with GPT Image 2.
Save the result and show me the generated path.
```

The agent calls `generate_image`; the local browser operates the user's own
Genspark session; the generated file is saved under `~/Genspark-MCP/outputs`.
The same pattern works for video with `generate_video`.

## GPT Image 2 and “unlimited” usage

Genspark's current [membership guidance](https://www.genspark.ai/helpcenter/membership-plans)
lists unlimited AI Image Agent image creation at zero credit cost for Plus and
Pro plans. The same guidance says that session-based rate limits and abuse
guardrails still apply. This MCP does not bypass those limits.

The accurate promise is therefore:

> If the user's Genspark plan and current UI provide access to GPT Image 2,
> the user can request it repeatedly from Claude Code, Codex CLI, or another
> local MCP client, subject to Genspark's account, session limits, and policies.

The [GPT Image 2 page](https://www.genspark.ai/tools/gpt-image-2) describes the
model's current quality and size options. The MCP passes the requested model,
size, and aspect ratio to the UI and refuses to claim success when the UI does
not confirm the requested setting.

## Supported clients

| Client | Support | Setup |
| --- | --- | --- |
| Claude Code | Yes | `install.sh` registers both servers and `/image`/`/video` commands |
| Codex CLI | Yes | Add the two local stdio servers with [`docs/CLIENTS.md`](docs/CLIENTS.md) |
| Other MCP clients | Yes, if they support local stdio | Use `mcp-config.template.json` |

The MCP protocol is client-neutral. The package's installer is intentionally
conservative and only edits Claude Code configuration; Codex and other client
configurations are shown explicitly so an existing setup is not overwritten.

## Features

### Image generation

- `GPT Image 2` by default; also supports the models exposed by the current
  image UI, such as Nano Banana Pro, Nano Banana 2, Flux 2 Pro, Ideogram V3,
  Recraft V3, Seedream, and Qwen Image 2.
- Aspect ratios from `21:9` through `9:21`, including `1:1`, `16:9`, and
  `9:16`.
- Image sizes `0.5K`, `1K`, `2K`, and `4K`, plus automatic selection.
- Up to 10 local reference images (`png`, `jpg`, `jpeg`, `webp`, `gif`, `bmp`,
  `heic`, or `avif`).
- Reference-image attachment is fail-closed: if one requested image is not
  attached, generation is stopped instead of silently generating a different
  image.
- Results are saved locally and can be returned inline to the MCP client.
- A no-browser `list_options` call exposes the known model, size, and ratio
  choices.

### Video generation

- Text-to-video and image-to-video through the current Genspark video UI.
- Model-specific choices such as Gemini Veo, Kling, Seedance, PixVerse,
  MiniMax, Vidu, Wan, Runway, and other models visible to the logged-in user.
- Model, aspect ratio, resolution, duration, count, audio, fast mode, tier,
  and auto-prompt controls.
- Ordered input images for reference, motion-control, and first/last-frame
  workflows.
- `list_video_options` reads the live UI because video controls vary by model.
- Fail-closed settings: if an explicitly requested setting cannot be applied
  and read back, the MCP refuses to submit a generation.
- `dry_run=true` applies and verifies the requested settings without clicking
  submit. Use it before a high-tier or multi-output request.

The complete parameter and return-value reference is in
[`docs/FEATURES.md`](docs/FEATURES.md).

## MCP tools

### `genspark-image-mcp`

| Tool | Generates media? | Purpose |
| --- | ---: | --- |
| `generate_image` | Yes | Generate, save, and optionally return image data |
| `check_session` | No | Check the local Genspark image session |
| `list_options` | No | Return known image models, sizes, and ratios |

`generate_image` arguments:

| Argument | Default | Meaning |
| --- | --- | --- |
| `prompt` | required | Japanese or English image instruction |
| `model` | `GPT Image 2` | Model name or partial match |
| `aspect_ratio` | automatic | For example `16:9`, `1:1`, or `9:16` |
| `image_size` | automatic | `0.5K`, `1K`, `2K`, or `4K` |
| `timeout` | `240` | Maximum wait in seconds |
| `include_images` | `true` | Return image data inline as well as saved paths |
| `reference_images` | empty | One path, a list, or comma/newline-separated local paths; maximum 10 |

### `genspark-video-mcp`

| Tool | Generates media? | Purpose |
| --- | ---: | --- |
| `generate_video` | Yes, unless `dry_run=true` | Generate and save MP4 output |
| `check_video_session` | No | Check the local Genspark video session |
| `list_video_options` | No, but opens a browser | Read model-specific live options |

`generate_video` arguments:

| Argument | Default | Meaning |
| --- | --- | --- |
| `prompt` | required | Japanese or English scene/story instruction |
| `images` | empty | Ordered local paths for image-to-video; maximum 10 |
| `model` | page default | Exact or partial model name |
| `aspect_ratio` | model default | `Auto`, `9:16`, or `16:9` |
| `resolution` | model default | For example `720p`, `1080p`, or `4k` |
| `duration` | model default | Model-specific seconds |
| `count` | model default | Usually `1` or `2` |
| `audio` | unchanged | Enable or disable audio when supported |
| `fast_mode` | unchanged | Enable or disable fast mode when supported |
| `tier` | model default | `Lite`, `スタンダード`, or `Ultra` |
| `auto_prompt` | unchanged | Whether Genspark rewrites the prompt |
| `timeout` | `1200` | Maximum wait in seconds |
| `dry_run` | `false` | Apply/read back settings without submitting |

## Install

Requirements:

- macOS
- Python 3.10 or newer
- Claude Code, Codex CLI, or another local stdio MCP client
- A Genspark account with access to the requested feature
- Internet access for Python packages and Camoufox binaries

```bash
git clone https://github.com/stockvalue/genspark-mcp.git
cd genspark-mcp
bash ./install.sh
```

The installer:

1. Copies the package to `~/Genspark-MCP`.
2. Creates `~/Genspark-MCP/.venv`.
3. Installs pinned Python dependencies.
4. Downloads the Camoufox browser binary.
5. Registers `genspark-image-mcp` and `genspark-video-mcp` for Claude Code.
6. Registers `/image` and `/video` slash commands.
7. Creates empty `profile_user` and `outputs` directories.

Existing Claude MCP entries or slash commands with different contents are not
overwritten automatically. See the installer options with:

```bash
bash ./install.sh --help
```

## Login and verify before generating

Login must be performed by the account owner in the visible browser. Do not
send a password, MFA code, cookie, or browser profile to an agent or another
person.

```bash
cd ~/Genspark-MCP
.venv/bin/python login.py
.venv/bin/python verify_setup.py
.venv/bin/python verify_setup.py --check-login
```

`verify_setup.py` starts both MCP servers and checks all six expected tools. It
does not generate an image or video. `--check-login` additionally checks the
current local session; it returns a non-zero status when either session is not
logged in, which is intentional.

Restart Claude Code or Codex after adding the MCP so the client reloads its
configuration. Client-specific commands are in
[`docs/CLIENTS.md`](docs/CLIENTS.md).

## Examples

### Claude Code

After installation, use the slash command:

```text
/image 16:9の広告用ヒーロー画像。モデルはGPT Image 2、サイズは2K。
```

Or ask Claude Code directly to call:

```text
Use mcp__genspark-image-mcp__generate_image with model="GPT Image 2",
aspect_ratio="16:9", image_size="2K", and include_images=true.
```

For video:

```text
Use mcp__genspark-video-mcp__generate_video with model="Gemini Veo 3.1",
duration=8, resolution="1080p", audio=false, and dry_run=true first.
```

### Codex CLI

Register the local servers once, then ask Codex to call them:

```bash
codex mcp add genspark-image-mcp \
  --env "GENSPARK_PROFILE=$HOME/Genspark-MCP/profile_user" \
  --env "GENSPARK_OUTPUT_DIR=$HOME/Genspark-MCP/outputs" -- \
  "$HOME/Genspark-MCP/.venv/bin/python" "$HOME/Genspark-MCP/gs_mcp_server.py"

codex mcp add genspark-video-mcp \
  --env "GENSPARK_PROFILE=$HOME/Genspark-MCP/profile_user" \
  --env "GENSPARK_OUTPUT_DIR=$HOME/Genspark-MCP/outputs" -- \
  "$HOME/Genspark-MCP/.venv/bin/python" "$HOME/Genspark-MCP/gs_video_mcp_server.py"
```

Then start a new Codex session and request `GPT Image 2` by name. The MCP
client, not a hosted service, invokes the local browser.

### Direct local CLI

The image and video files also expose a JSON-producing CLI for scripts that do
not need MCP framing:

```bash
cd ~/Genspark-MCP
printf '%s' 'A clean product hero image with Japanese typography' \
  | .venv/bin/python gs_mcp_server.py generate --prompt - --model 'GPT Image 2' \
    --aspect-ratio 16:9 --image-size 2K
```

The direct CLI is optional; MCP clients should normally use the tool surface.

## Output and local data

- Login data stays under `~/Genspark-MCP/profile_user`.
- Generated files stay under `~/Genspark-MCP/outputs`.
- The public repository contains none of those directories or their contents.
- `genspark_state.json`, cookies, MFA data, and generated private media must
  never be committed or attached to an issue.

## Limitations and safety boundary

This package automates a web UI rather than an official Genspark API. A UI
change, login challenge, rate limit, plan restriction, or account state can
make a tool fail. Generated images and videos are external side effects: check
the model, resolution, duration, tier, count, and output path before submitting.

Use only your own account or an account you are explicitly authorized to use.
Do not share credentials, reuse another person's browser profile, resell
access, bulk-extract service data, or operate a hosted third-party proxy with
this package. Read the current [Genspark usage guidance](https://www.genspark.ai/helpcenter/membership-plans)
and [terms](https://www.genspark.ai/terms) before use.

## Troubleshooting

Start with [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md). Common safe
checks are:

```bash
cd ~/Genspark-MCP
.venv/bin/python verify_setup.py
.venv/bin/python verify_setup.py --check-login
.venv/bin/python -m pip show mcp camoufox playwright
```

If the UI changed, report the redacted error kind, macOS version, Python
version, MCP client, requested model/settings, and whether `verify_setup.py`
passed. Never include credentials, cookies, or a browser profile archive.

## Development and verification

```bash
python3 -m pip install -r requirements.txt
python3 scripts/check_public_tree.py
python3 -m compileall -q *.py scripts tests
python3 -m unittest discover -s tests -v
```

CI runs the public-tree check, compilation, and no-generation tests. It does
not log in or spend image/video credits. The current local verification status
is that all six MCP tools and the isolated installer path have been checked
without media generation; live generation still depends on the user's account
and the current Genspark UI.

## More documentation

- [`docs/CLIENTS.md`](docs/CLIENTS.md) — Claude Code, Codex CLI, and generic MCP configuration
- [`docs/FEATURES.md`](docs/FEATURES.md) — complete tool parameters, behavior, and return data
- [`docs/TROUBLESHOOTING.md`](docs/TROUBLESHOOTING.md) — safe diagnosis and issue reports
- [`docs/LAUNCH_POSTS.md`](docs/LAUNCH_POSTS.md) — launch copy, topics, release text, and metrics
- [`AI_SETUP_INSTRUCTIONS.md`](AI_SETUP_INSTRUCTIONS.md) — rules for an agent helping with setup
- [`SECURITY.md`](SECURITY.md) — security reporting boundary

## 日本語まとめ

`genspark-mcp` は、利用者自身のGensparkアカウントをローカルブラウザで使い、Claude Code・Codex CLIなどのコーディングエージェントから画像・動画生成を呼び出す非公式MCPです。画像サーバーの既定モデルは `GPT Image 2` で、モデル・比率・サイズ・参照画像を指定できます。動画サーバーはモデルごとの設定を実UIから読み、指定と異なる条件で送信しないfail-closed設計です。

GensparkのPlus/Pro側に画像Agentの無制限枠が表示される場合でも、セッション単位のレート制限と利用規約上のガードレールがあります。「無限に使える」と断定するのではなく、「自分の契約・アカウント・現在のUIの範囲で、CLIから繰り返し呼べる」と理解してください。

## License

MIT. See [LICENSE](LICENSE).