FOR AI AGENTS

Let your agent create images with Sparkles

Connect Claude Code, Claude Desktop, Cursor or another MCP client to your Sparkles account. Install the open-source Sparkles Image MCP, sign in once, and let your agent generate images and GIFs from a prompt.

Sparkles Image MCP is a local MCP server. It uses your existing Sparkles account and Credits; you never give the agent a password or an API key. Images made through MCP appear in the same Library as images created on the website.

Install in about a minute GitHub repository

Install in about a minute

Choose one method. The Claude Code plugin is the quickest. Use the manual configuration for Claude Desktop, Cursor, or another MCP client.

Claude Code plugin

Inside Claude Code, run these two commands. The plugin includes the MCP server and the sparkles-image skill.

/plugin marketplace add sparkles-mcp/sparkles-image-mcp
/plugin install sparkles-image@sparkles-image-mcp

Manual MCP configuration

Add this server to your MCP client configuration. It works with any client that supports stdio MCP servers.

{
  "mcpServers": {
    "sparkles-image": {
      "command": "npx",
      "args": ["-y", "github:sparkles-mcp/sparkles-image-mcp", "serve"]
    }
  }
}

Or use the setup CLI

The CLI installs the agent skill, prints the client configuration, and starts the browser login. Run doctor at any time to check the connection.

npx -y github:sparkles-mcp/sparkles-image-mcp init
npx -y github:sparkles-mcp/sparkles-image-mcp doctor

Send this to your agent

Not sure how to configure your client? Copy this prompt and send it to your agent. It will add the server and start the login.

Send this to your agent

Configure the Sparkles Image MCP for this client.

Server command: npx
Server args: -y github:sparkles-mcp/sparkles-image-mcp serve

If this is Claude Code, run:
claude mcp add --scope user sparkles-image -- npx -y github:sparkles-mcp/sparkles-image-mcp serve

Then start the sparkles-image login tool and wait while I approve access in the browser. Do not generate any image until I ask. Each generation spends my Sparkles Credits.

Do not install the Claude Code plugin and a manual server entry at the same time. They use the same server name.

Sign in once, approve the scopes

Login opens sparkles-editor.com in your browser and waits for a local callback on 127.0.0.1. The consent page shows the app and the signed-in account. Tokens stay on your machine; revoke access at any time from Account → Connected MCP apps. The access token expires after 15 minutes and refreshes automatically.

images:generateSubmit and cancel image jobs.
images:readRead job status, your library, and generated images.
account:readRead your Credits balance and usage.

What the agent can do

These tools are available after login. Image generation spends Credits; reading tools do not.

generate_imageGenerate 1-4 images or one animated GIF from a prompt.
get_imageCheck one job and return its image when it is ready.
list_imagesList recent images and their job status.
check_image_jobsCheck up to 50 jobs without downloading images.
cancel_image_jobsCancel queued jobs.
list_image_modelsList available models, qualities, and GIF support.
get_credit_balanceRead the available Credit balance.
get_credit_usageRead recent charges and refunds.
loginOpen the browser login when authorization is needed.

Images appear in your Sparkles Library

Images generated through MCP are ordinary Sparkles images. They appear in Library → Artwork and in the image workspace's recent artwork strip, and follow the same retention as the website: 1 day after generation, or 28 days while a subscription is active. Save an image permanently if you want to keep it.

Open Sparkles Library → Artwork

Credits and moderation

Every generation spends Credits from your signed-in account. The catalog may show 0 for usage-based models; the actual charge appears in get_credit_usage and in your billing history. Prompts go through the same moderation as images created on the site. Rejected prompts are reported as errors and should not be rephrased to evade moderation.

Common questions

Login does not open: Run the CLI login command; it prints the authorization URL so you can open it manually.
login_required or login_expired: Sign in again. If it repeats, revoke the old grant in Account → Connected MCP apps.
insufficient_credits: Top up or reduce the request. The agent should not retry blindly.
The image is still generating: Ask the agent to call get_image with the job id. Do not submit the same prompt again.
image_too_large: The image exceeds the 6 MB inline limit. Open it in Library → Artwork or download it there.
The wrong site opens: Check SPARKLES_ISSUER if you use a staging or self-hosted site.

Links

The MCP client is open source under MIT. It uses the public /api/mcp API and does not include the Sparkles website code, billing logic, moderation rules, or secrets.