genspark-mcp

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:

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.

Related MCP server: mcp-media-engine

GPT Image 2 and “unlimited” usage

Genspark's current membership guidance 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 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

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.

MCP tools

genspark-image-mcp

generate_image arguments:

genspark-video-mcp

generate_video arguments:

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

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 ./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.

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.

Examples

Claude Code

After installation, use the slash command:

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

Or ask Claude Code directly to call:

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:

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:

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:

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 and terms before use.

Troubleshooting

Start with docs/TROUBLESHOOTING.md. Common safe checks are:

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

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 — Claude Code, Codex CLI, and generic MCP configuration

• docs/FEATURES.md — complete tool parameters, behavior, and return data

• docs/TROUBLESHOOTING.md — safe diagnosis and issue reports

• docs/LAUNCH_POSTS.md — launch copy, topics, release text, and metrics

• AI_SETUP_INSTRUCTIONS.md — rules for an agent helping with setup

• 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.