Sparkles Image MCP
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Sparkles Image MCP
An open-source Model Context Protocol server that generates images and animated GIFs with a Sparkles Editor account.
The plugin runs locally and speaks MCP over stdio. The user signs in through the Sparkles website with OAuth, and the plugin calls the site's public /api/mcp API. Image generation, credits, moderation, and storage stay on Sparkles.
MCP client (Claude Code, Claude Desktop, Cursor, ...)
│ stdio / JSON-RPC
▼
sparkles-image-mcp (this repository)
│ HTTPS + OAuth 2.1 PKCE
▼
Sparkles Editor
/oauth/authorize /api/oauth/token /api/mcp/*
│
▼
Image generation · Credits · Moderation · Storage · Private libraryWhat it provides
Generate 1-4 images from one prompt, or one animated GIF.
Check, list, fetch, and cancel image jobs.
Read the account's credit balance and recent usage.
Install an agent skill that explains the workflow to the model.
Generated images are ordinary Sparkles images: they appear in the site's Library and in the image workspace's recent artwork history, with the same retention rules as images created on the website.
Not included in v1: image editing, reference-image uploads, video generation, and a remote HTTP transport.
Related MCP server: gpt-image-2-mcp
Requirements
Node.js 20 or newer.
A Sparkles Editor account with available image credits.
A local browser for the one-time login.
Install
Claude Code plugin (recommended)
Inside Claude Code:
/plugin marketplace add sparkles-mcp/sparkles-image-mcp
/plugin install sparkles-image@sparkles-image-mcpThe plugin supplies the MCP server entry and the sparkles-image skill. After installing, ask the agent to generate an image. If it reports that login is required, it will call the login tool and open the authorization page.
Manual MCP configuration
Use this when you do not want the plugin, or when configuring Claude Desktop, Cursor, or another MCP client.
Claude Code:
claude mcp add --scope user \
--env SPARKLES_ISSUER=https://sparkles-editor.com \
--env SPARKLES_API_BASE=https://sparkles-editor.com/api/mcp \
--env SPARKLES_RESOURCE=https://sparkles-editor.com/api/mcp \
--env SPARKLES_CLIENT_ID=sparkles-image-mcp \
--env SPARKLES_SCOPE="images:generate images:read account:read" \
--env SPARKLES_CONFIG_DIR="$HOME/.config/sparkles-image-mcp" \
sparkles-image -- npx -y github:sparkles-mcp/sparkles-image-mcp serveClaude Desktop / Cursor (JSON):
{
"mcpServers": {
"sparkles-image": {
"command": "npx",
"args": ["-y", "github:sparkles-mcp/sparkles-image-mcp", "serve"],
"env": {
"SPARKLES_ISSUER": "https://sparkles-editor.com",
"SPARKLES_API_BASE": "https://sparkles-editor.com/api/mcp",
"SPARKLES_RESOURCE": "https://sparkles-editor.com/api/mcp",
"SPARKLES_CLIENT_ID": "sparkles-image-mcp",
"SPARKLES_SCOPE": "images:generate images:read account:read",
"SPARKLES_CONFIG_DIR": "/home/you/.config/sparkles-image-mcp"
}
}
}
}Do not install the plugin and a manual entry named sparkles-image at the same time. They would start two servers with the same name.
init prints all resolved settings, including the client id, resource indicator, and scopes. The Claude Code plugin uses the production defaults; if you change the issuer or OAuth client, use the manual configuration and give login and serve the same environment.
CLI setup helper
The same package also has a terminal CLI:
npx -y github:sparkles-mcp/sparkles-image-mcp initinit installs SKILL.md into ~/.claude/skills/sparkles-image/, prints client configuration, and starts the browser login. Options:
Option | Meaning |
| Install the skill in |
| Print configuration and install the skill without opening the browser. |
| Replace an existing, different |
Other commands: serve, login, logout, doctor, version, help.
npx -y github:sparkles-mcp/sparkles-image-mcp doctordoctor prints the resolved issuer, API base, config directory, login state, balance, model catalog status, and authorization-metadata status. It does not print tokens.
Signing in
Login uses OAuth 2.1 authorization code with PKCE (S256) and a loopback redirect on 127.0.0.1. The plugin is a public client and has no client secret.
The consent page shows the requesting app, the signed-in account, and the requested scopes:
Scope | Allows |
| Submit and cancel image jobs. |
| Read job status, the image library, and generated image bytes. |
| Read the credit balance and usage history. |
The access token is a 15-minute ES256 JWT. The refresh token rotates on every use. Credentials are stored in:
$SPARKLES_CONFIG_DIR/credentials.json, or~/.config/sparkles-image-mcp/credentials.json(or$XDG_CONFIG_HOME/sparkles-image-mcp).
The file is written atomically with 0600 permissions. The plugin never sees the account password and never writes tokens to logs or tool output.
Signing out
npx -y github:sparkles-mcp/sparkles-image-mcp logoutLogout revokes the refresh token on the site and deletes the local credentials. If the site cannot confirm revocation (for example, while offline), the local file is still deleted, but the CLI warns that the server-side grant may remain. In that case, revoke it from Account → Connected MCP apps at https://sparkles-editor.com/account.
Removing the plugin or deleting the credentials file does not by itself revoke a grant that is still active on the site. Use logout or the account page.
Tools
Tool | Purpose | Read-only |
| Open the browser authorization page and wait for approval. | No |
| Generate 1-4 images or one GIF. | No |
| Check one job and return its image when complete. | Yes |
| List recent image jobs (metadata only). | Yes |
| Check up to 50 jobs without downloading images. | Yes |
| Cancel queued jobs. | No |
| List models, qualities, formats, and the default model. | Yes |
| Read the available credit balance. | Yes |
| Read recent charges and refunds. | Yes |
generate_image
Parameter | Type | Default | Notes |
| string | required | 3-32,000 characters. Write a full visual prompt. |
| string | site default | Use an id from |
| enum |
|
|
| string |
|
|
| enum |
|
|
| integer |
| 1-4. GIF output requires |
| enum | — |
|
| integer |
| GIF only: 2-16 frames. |
| integer |
| GIF only: 20-2,000 ms, a multiple of 10. |
| UUID | generated | Idempotency key. Reuse it only when retrying the identical request after a network error. |
| integer |
| 0-30. Keep the whole tool call below the MCP client's usual 60-second timeout. |
The result contains job metadata and, for completed jobs, standard MCP image content. Inline images are capped at 6 MB combined per response so the JSON-RPC message stays below the 10 MiB stdio limit. If an image is larger, or the download budget is exhausted, the tool returns the job id and asks the agent to call get_image. Each completed image can then be fetched separately.
If the job is still running when the wait window ends, the result has pending: true; call get_image later instead of submitting the prompt again.
get_image
Parameter | Type | Notes |
| UUID | Job id from |
Returns the job status and, when the job is complete, the image bytes. A job that is no longer stored returns not_found.
list_images
Parameter | Type | Default | Notes |
| integer |
| 1-30 per page. |
| enum |
|
|
| boolean |
| Only permanently saved images. |
| string | — |
|
This returns metadata only. Use get_image for the bytes.
check_image_jobs
Parameter | Type | Notes |
| UUID array | 1-50 ids. |
cancel_image_jobs
Parameter | Type | Notes |
| UUID array | Up to 50 queued jobs. |
| UUID array | Up to 50 creation request ids. |
Provide at least one of the two. Running and completed jobs cannot be cancelled.
list_image_models
Returns the available model ids, their qualities, GIF support, the site default model, and the supported output formats. Call it before choosing a non-default model or GIF.
get_credit_balance
Returns the spendable balance, wallet and subscription portions, unlimited status, and subscription end date when present. Values use the same display units as the Sparkles website.
get_credit_usage
Parameter | Type | Default | Notes |
| integer |
| 1-1,000,000. |
| integer |
|
|
Negative amounts are charges; positive amounts are refunds.
Images in the Sparkles library
Every MCP generation creates a normal Sparkles image job for the signed-in account. Completed images appear in:
Library → Artwork: https://sparkles-editor.com/library?view=artwork
The recent artwork strip in the image workspace.
The retention rules are the same as the website:
New ordinary temporary images: 1 day after generation completes, or 28 days while a subscription is active.
Images added to an infinite canvas: 7 days from first addition.
Permanently saved images: kept within the account's storage allowance.
Existing images keep their originally recorded expiry.
Download or permanently save an image you want to keep. The MCP result also prints the library link when at least one image completed.
Credits and moderation
Every generation spends credits from the signed-in Sparkles account. The model catalog may report credits: 0 for usage-based models; the actual charge appears in get_credit_usage and in the site's billing history. The plugin does not promise a fixed price or a refund.
Prompts go through the same moderation pipeline as images created on the website. A rejected prompt is returned as an error. Do not rephrase a rejected prompt to evade moderation.
The plugin does not generate extra test images, bypass rate limits, or call the site's internal billing or model services.
Configuration
Variable | Default | Meaning |
|
| Site origin used for OAuth and the API. |
|
| Public MCP API base. |
|
| OAuth resource indicator. |
|
| Pre-registered public OAuth client id. |
|
| Space-separated scopes to request. The server enforces the grant; a call outside it fails with |
|
| Credential directory. Must be the same for |
| — | Set to |
| — | Cloudflare Access service token id, for private deployments. |
| — | Cloudflare Access service token secret. |
| — | Cloudflare Access cookie for local verification only. Never commit it. |
The Access variables are only for deployments protected by Cloudflare Access, such as a staging site. Production sparkles-editor.com does not require them.
If you change SPARKLES_CONFIG_DIR, set it in both the login command and the MCP server environment, or the server will not find the credentials.
Troubleshooting
Every tool error includes a code in square brackets, for example [insufficient_credits]. Start with doctor.
Code | Meaning | What to do |
| No local credentials. | Call the |
| The refresh token was rejected or revoked. | Sign in again. If it repeats, revoke the old grant on the account page. |
| The user declined the authorization page. | Run login again when ready. |
| No approval within 5 minutes. | Run login again. |
| The local loopback listener could not start. | Check that |
| A redirect indicates Cloudflare Access. | Configure the Access service token variables, or use a site without Access. |
| The authorization server metadata names an unexpected issuer or origin. | Check |
| The account cannot pay for the request. | Top up on the site or reduce the request; do not retry blindly. |
| The grant lacks a scope needed by the tool. | Sign in again and approve all scopes, or fix |
| The token was rejected. | Run |
| The catalog changed or the value is unsupported. | Call |
| Invalid size, frame options, or idempotency id. | Check the parameter limits above. |
| Model, quality, or price changed between catalog read and submission. | Refresh the catalog and confirm the new price with the user. |
| The site asked the client to slow down. | Wait for |
| The job or stored image does not exist or has expired. | Check |
| The original and the preview both exceed 6 MB. | Open the image in the Sparkles library instead. |
| The image download failed or had an unexpected format. | Retry |
| The request did not complete. It may still be processing. | Call |
| Image generation is disabled or has no models. | Try later; check the site. |
| The MCP client cancelled the call. | No action needed. |
If login opens the wrong site, check SPARKLES_ISSUER. If the browser does not open, the CLI prints the authorization URL; open it manually.
Upgrade and uninstall
CLI / manual MCP entry:
npx -y github:sparkles-mcp/sparkles-image-mcpalways runs the currentmainfrom GitHub. No separate upgrade step.Claude Code plugin: update or remove it from the
/pluginmenu.Manual Claude Code entry:
claude mcp remove sparkles-image.Skill: delete
~/.claude/skills/sparkles-image/(or./.claude/skills/sparkles-image/).Credentials: run
logout, then delete$SPARKLES_CONFIG_DIRif it still exists.
Privacy and security
Images, prompts, and account data are handled by Sparkles under its Privacy Policy.
The plugin stores only OAuth credentials on the local machine. It does not store prompts or images outside the MCP client's own conversation.
Tokens are scoped, short-lived, and revocable from the account page.
Report a suspected vulnerability privately to support@sparkles-editor.com. Do not open a public issue containing exploit details, tokens, or private images.
Development
npm install
npm test
node src/cli.mjs help
node src/cli.mjs doctorTests use node:test, a temporary config directory, and a local fake HTTP server. They do not call the production site, spend credits, or read real user data.
To point a development build at an isolated site:
SPARKLES_ISSUER=https://t-d.example.com \
SPARKLES_API_BASE=https://t-d.example.com/api/mcp \
SPARKLES_CONFIG_DIR=/tmp/sparkles-mcp-test \
node src/cli.mjs doctorOpen-source boundary
This repository contains only the MCP client, its OAuth/PKCE client, the agent skill, and tests. It does not contain the Sparkles website's server code, authorization server implementation, consent page, moderation rules, prompt templates, model routing, pricing tables, database schema, or secrets. The plugin depends only on the documented public OAuth and /api/mcp contracts.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Generate on-brand images from your AI agent: design, edit, and render templates over MCP.
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
Generate AI images and videos from any compatible MCP client.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables MCP-compatible clients to generate images via the Agnes API and manage local image utilities, including downloading images from secure URLs and validating local image files.427 npmMIT
- AlicenseAqualityBmaintenanceEnables MCP clients to generate images and iteratively edit them using OpenAI's gpt-image-2 models, with session management, background job polling, and local file saving.8556 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables coding agents and other MCP clients to generate images from text prompts and edit, restyle, or extend existing images through an OpenAI-compatible /v1/images API. Results are returned both inline as image content blocks and as files saved to disk, so agents can view and reuse them within a normal task.274 npm1MIT
- AlicenseAqualityBmaintenanceEnables MCP clients to generate images, edit existing ones, and create matching image sets using either the Codex CLI or the OpenAI Images API. It returns previews and saved file paths so agents can inspect results and continue iterating.3206 npm1MIT