Adobe Firefly MCP Server & CLI

What is the Adobe Firefly MCP server & CLI?

The Adobe Firefly MCP server & CLI is a free, open source program that lets AI agents generate and transform media through Adobe Firefly Services for you, in 2 ways. The MCP server is what an AI app like Claude, Codex or Cursor connects to, through MCP (Model Context Protocol), the open standard AI apps use to call outside tools.

You ask in plain language. Your AI picks the right tool, and the server makes the call to Adobe through its documented Firefly Services API.

The CLI is the same program as commands. firefly-cli list-custom-models runs the same code your AI runs when you ask which custom models are available, whether an agent like Claude Code runs it or you do.

What can you ask it?

Once it's set up, you ask the way you'd ask an assistant. These are real prompts it handles:

Try asking
Generate a square product image of a ceramic cup in warm morning light with Image 5.
Use this uploaded reference and change its background to a soft blue studio wall.
Fill this masked region with a small green plant.
Expand this image for a landscape hero.
Generate a five-second video of a slow camera movement through a sunlit forest.
Which custom models can this Adobe project access?
Check the existing video job before submitting another generation.

Image generation needs Firefly Services API entitlement and uses your Adobe credits. Your AI must confirm a requested paid operation before the server submits it.

How to install the Adobe Firefly MCP server

Pick your app in the install box. Version 2.0.0 is available on npm, and the matching Claude Desktop extension is attached to its GitHub release. Use @latest in MCP settings and restart the server to pick up an update.

Set up your Adobe Firefly Services project

Adobe’s authentication prerequisites describe the provisioned project and API access. If you do not have a project yet, check access with your Adobe representative or organization administrator.

The login command explains these steps. It does not open a browser or store a secret. The program does not load an .env file automatically.

The desktop extension asks for the same values in its local settings and marks the client-secret field sensitive. Its archive includes the server and production dependencies, with no credentials.

Adobe tutorial aliases

FIREFLY_SERVICES_CLIENT_ID, FIREFLY_SERVICES_CLIENT_SECRET and FIREFLY_SERVICES_ACCESS_TOKEN are accepted as aliases. An existing access token can replace the secret. Access tokens expire; the client ID and secret let the running server obtain a fresh token in memory.

For user-specific custom-model access, FIREFLY_USER_TOKEN is optional. One instance uses one credential set; connect separate server instances for separate Adobe projects.

Check that it works

Run the doctor to check local configuration. Add --network to exchange OAuth credentials, or validate an existing token with a custom-model read, without generating media or spending generation credits.

npx -y @thenavidm/firefly-mcp-cli@latest doctor --network

Authentication success does not prove entitlement to every API endpoint. Adobe checks that when the operation runs. An authenticated live API test of this version remains pending.

Use the Adobe Firefly CLI

The CLI is the same 14 tools as commands. AI agents that run commands, like Claude Code, Codex and OpenCode, use it on their own, and you can type the same commands in a terminal or a script.

Every tool name becomes a command with dashes, so list_custom_models runs as firefly-cli list-custom-models.

npm install -g @thenavidm/firefly-mcp-cli@latest
firefly-cli
firefly-cli generate-image5 --help
firefly-cli schema generate-image5
firefly-cli list-custom-models --agent --select data,links
firefly-cli generate-image5 --prompt "A ceramic cup in warm morning light" --aspectRatio 1:1 --resolutionLevel 4MP --confirm --agent
firefly-cli get-job-status --jobId JOB_ID_FROM_RESULT --agent

The bare firefly-cli lists every command, and firefly-cli <command> --help shows what a command takes. The ten paid media operations require --confirm, the CLI equivalent of confirm: true. Uploads do not require that flag. --agent and --yes never authorize spending by themselves.

These flags work on every command:

A script can branch on the exit code:

MCP server or CLI: which one?

Both surfaces call the same server tools. MCP connects them directly to an AI chat; the CLI gives an agent with a terminal the same operations as commands.

The token comparison is pending. We measure four real Claude Code usage differences: every tool loaded, default tool search, the skill read once, and its recurring description line. Commands, help, selected schemas, results and reasoning also contribute to complete task cost.

There is no measured efficiency percentage for this version yet. Standing context and the total cost of a successful task will be reported separately.

Image 5, references and existing jobs

Image 5 has its own generate_image5 tool and v4 request schema. It takes aspectRatio, resolutionLevel, modelSpecificPayload and referenceBlobs. The older generate_image tool uses a different v3 schema. Read the generated schema before constructing a request.

An Image 5 reference edit accepts one reference image and requires the aspect ratio to be omitted or auto. Array arguments are repeatable CLI flags, with one JSON object per --referenceBlobs argument. Do not pass a JSON array where a single array item is expected.

Upload a reference

firefly-cli upload-image --filePath /absolute/path/reference.png --agent
firefly-cli generate-image5 --prompt "Change the background to soft blue" --referenceBlobs '{"source":{"uploadId":"UPLOAD_ID_FROM_RESULT"},"usage":"general"}' --confirm --agent

Uploads accept JPEG, PNG, WebP, TIFF and JXL, with a 15 MB limit. An upload ID is valid for seven days. Only upload files the user requested. A path refers to the computer running the server, including when Claude Desktop launches it.

Poll without spending twice

firefly-cli generate-video --prompt "Slow movement through a sunlit forest" --wait=false --confirm --agent
firefly-cli get-job-status --jobId JOB_ID_FROM_RESULT --agent

The video API creates a five-second video. wait=false returns an async job immediately. A submission timeout can have an unknown outcome, so inspect that job before trying another generation. The client does not automatically retry paid submissions.

Download the result

Use --download with a completed media operation to save the result in FIREFLY_OUTPUT_DIR, defaulting to ~/outputs/images. Downloads default off, require wait=true and use unique filenames. Each file is limited to 250 MB. The CLI returns URLs and optional paths as JSON; it does not print binary media.

Composite tools have different inputs

generate_object_composite generates a scene around a product image. precise_composite and adaptive_composite accept a supplied background and object. Use their schemas instead of mixing the payloads.

How this compares with Adobe and other repos

Adobe publishes the Firefly REST API and JavaScript SDK. A dedicated Adobe-published Firefly task CLI or MCP server was not identified in the official docs reviewed for this version. That is a scoped finding, not a claim that none exists anywhere.

This implementation adds a first-class CLI and a local desktop bundle around the same 14 tools. Other community repos have different strengths: FocusGTS also covers Photoshop and Lightroom, and another image/video MCP provides a remote HTTP transport.

The comparison does not claim our package is faster or cheaper. Those claims need matched successful tasks, including discovery, skill, command and result tokens, latency and Adobe credits. The repo comparison records the reviewed sources and limits.

A discrepancy in Adobe’s docs

The Image 5 migration article describes fields differently from the current OpenAPI operation and its examples. This version uses the operation schema, records the exact snapshot hash, and tests that request shape. Live account validation is still needed.

Every Adobe Firefly tool

All 14 tools, grouped the way the repo groups them. 3 only read, and 11 change something or spend Adobe credits.

Image generation and editing

Product composites

Video generation

Reference uploads

Existing jobs

Account and custom models

Is the Adobe Firefly MCP server safe?

Media generation uses Adobe credits. All 10 paid media tools ask for explicit confirmation; they are marked Asks first in the tool reference. Uploading is a write, and credentials, custom models and existing jobs are reads.

The guard follows the existing Midjourney spending pattern. It confirms the operation the user requested and does not treat machine-readable mode as permission to spend.

Make it read-only

Set FIREFLY_READ_ONLY=1 to hide every generation and upload tool, leaving 3 reads. FIREFLY_ALLOW_SPENDING=0 is the middle setting: uploads and reads remain available, while paid generation is blocked.

Keep a log of every write

Set FIREFLY_AUDIT_LOG to a file path. The server writes one line per attempted write, allowed or blocked.

Your data

Credentials come from private local environment or client settings. OAuth access tokens stay in memory. Requested prompts, URLs and uploads go directly to Adobe; there is no Navid-hosted relay. Audit records contain tool names and guard decisions without prompts or credentials. Requested downloads are local files. Adobe’s own service terms govern its processing and retention.

Adobe Firefly MCP server settings

Every setting is an environment variable, in your app's config or your shell.

Troubleshooting

Run the doctor first. It names the step that failed and the fix.

If the server doesn't show up in your app at all, run the command your app runs, in a terminal, and read the error.

Client setup and agent-guided installation

The install box gives each supported client its own command or config. INSTALL.md covers macOS, Windows and Linux, Claude Code, Codex, the desktop extension and manual config, Cursor, VS Code/Copilot, Windsurf, Zed, Gemini CLI, Docker and agents with a shell.

Let your AI help with setup
Help me install Adobe Firefly MCP Server & CLI using INSTALL.md. Check Node and the binary, let me configure my Adobe credentials privately, then run discovery and doctor --network. Do not generate media, upload files or spend credits during setup.

The CLI does not automatically register its skill. The package includes SKILL.md; make that file available through your client's supported skills location. Your agent should discover the current commands and schemas instead of constructing a payload from memory.

Arguments and payload shapes

The complete tool and argument reference documents every top-level field. For the exact current nested JSON Schema:

firefly-cli schema generate-image5
firefly-cli generate-image5 --help

An object uses a quoted JSON value. Arrays of objects use one repeated flag per object. A whole JSON array inside one referenceBlobs flag is not the same input. Unknown arguments, contradictory aliases and invalid source objects are refused before an Adobe request.

Community coverage and tradeoffs

The comparison checks source as well as package metadata at pinned revisions dated October 2, 2026. The full comparison records those revisions and the benchmark method.

FocusGTS also provides inline images and restricts local uploads to an allowed path. The remote MCP offers a different connection model and base64 uploads. These are meaningful alternatives; 14 tool names do not prove overall superiority. The terminal preview illustrates shipped tools and does not document a completed paid Adobe job.

Versions, changelog and updates

Read CHANGELOG.md for the full migration notes, and download desktop archives from GitHub Releases. Existing 1.x callers need to account for credit confirmation, opt-in downloads, strict arguments and Node 22 or newer.

For a global CLI update:

npm install -g @thenavidm/firefly-mcp-cli@latest
firefly-cli --version

MCP settings with @latest resolve the newer package when the server starts. They do not replace a process that is already running. Pinned versions stay pinned. Manually installed desktop extensions need the new .mcpb downloaded and installed; this repository does not claim automatic extension updates.

To remove the CLI, run npm uninstall -g @thenavidm/firefly-mcp-cli. Remove the MCP entry or desktop extension from each client too. Generated media, audit logs and private settings are separate and remain on your computer. Removing a package does not revoke an Adobe credential.

Validation and remaining evidence

Version 2.0.0 passes 41 behavioral tests, TypeScript build/typecheck, real MCP discovery, clean npm installation and both binary checks, desktop manifest validation and bundle discovery. GitHub CI passes on Linux and Windows with Node 22 and 24. Source, Git history and shipped artifacts pass secret scans.

The production dependency audit has no findings. SECURITY.md records an unpatched development-only advisory in the MCPB build tool, which is excluded from the npm runtime and desktop archive.

Live generation with an entitled Adobe account, actual installation inside desktop clients and the fresh Claude Code token comparison remain unverified. A failed or quota-blocked measurement is not reported as zero tokens, and this guide claims no measured efficiency percentage.