Firefly Services MCP Server

Model Context Protocol server for Adobe Firefly Services — exposes Firefly, Photoshop API, and Lightroom API endpoints as MCP tools that Claude Code, Cursor, and other MCP-compatible AI clients can call directly.

Built by FocusGTS. Not affiliated with or endorsed by Adobe Inc. or Anthropic, PBC.

See it in action

These are real images generated through this MCP server, live against the Adobe Firefly Services API — not mockups or stock art.

`firefly_generate_image`	`firefly_expand_image`	`firefly_generate_object_composite`

Text-to-image with Firefly V3	Canvas extended 1024 → 1408 px	Product composited into a generated scene

Generated in seconds from a Claude Code session, each by a single MCP tool call.

Status

v0.2.3 — 19 tools, fully implemented. The MCP server boots over stdio, implements the MCP protocol, and registers all 19 tools across Firefly (9), Photoshop API (6), and Lightroom API (4). Test coverage: 149 unit tests + 26 mocked integration tests passing.

Live validation status (against the Adobe Firefly Services sandbox): ✅ all 19 tools live-validated end-to-end.

Surface	Tools	Status
Firefly	9	✅ All 9 live-validated (auth, generate, generate-similar, expand, fill, object-composite, upload, video, job-status)
Lightroom API	4	✅ All 4 live-validated via GCS signed URLs (auto-tone, auto-straighten, apply-edits, apply-preset)
Photoshop API	6	✅ All 6 live-validated (document-manifest, edit-text, smart-object-replace, apply-edits, apply-actions via GCS; remove-background via the V2 API)

Every tool has been exercised end-to-end against the real Adobe Firefly Services API. The Photoshop document APIs and the Lightroom API write results to a caller-supplied pre-signed output_url (S3 / Azure / GCS); remove_background uses the V2 endpoint, which hosts the result itself. See docs/PRD.md for the release plan.

What this is

For developers using Claude Code (or any MCP-compatible client) who want to call Adobe Firefly Services directly from their AI workflow — generate images from prompts, expand and fill existing images, run Photoshop API operations on PSD templates, batch-process images through Lightroom — without leaving the editor.

This is not an Adobe SDK and not a replacement for one. It is a thin MCP adapter on top of Adobe's official SDKs (@adobe/firefly-apis, @adobe/photoshop-apis, @adobe/lightroom-apis, @adobe/firefly-services-common-apis). The SDKs do the real work; this server translates between MCP tool calls and SDK method calls. See ADR-001 for the rationale.

Install

Option 1 — From source (for development)

git clone https://github.com/Focus-GTS/firefly-services-mcp.git
cd firefly-services-mcp
npm install   # builds dist/ automatically via the prepare script

# Add to Claude Code
claude mcp add firefly-services -- node "$(pwd)/dist/server.js"

For the development loop without a build step:

claude mcp add firefly-services -- npx tsx "$(pwd)/src/server.ts"

Option 2 — From npm (recommended)

The package is published to npm, so install is one line:

claude mcp add firefly-services -- npx @focusgts/firefly-services-mcp

Published at npmjs.com/package/@focusgts/firefly-services-mcp.

Required environment variables

export FIREFLY_SERVICES_CLIENT_ID=<your client id from Adobe Developer Console>
export FIREFLY_SERVICES_CLIENT_SECRET=<your client secret>

The credentials must be an OAuth Server-to-Server credential pair issued via the Adobe Developer Console with Firefly Services API access provisioned on the workspace. See examples/install-claude-code.md for the full credential-acquisition walkthrough or the firefly-services-bootstrap skill for the FDE-grade detail.

Tools (v0.2 surface — 19 tools)

Firefly (9)

firefly_generate_image
firefly_generate_similar
firefly_expand_image
firefly_fill_image
firefly_generate_object_composite
firefly_generate_video
firefly_get_job_status
firefly_upload_image
firefly_check_auth

Photoshop API (6)

photoshop_smart_object_replace
photoshop_document_manifest
photoshop_apply_actions
photoshop_edit_text
photoshop_apply_edits
photoshop_remove_background

Lightroom API (4)

lightroom_apply_preset
lightroom_auto_tone
lightroom_auto_straighten
lightroom_apply_edits

Naming follows ADR-005: <product>_<action>_<object> in snake_case.

Architecture

Claude Code / Cursor
    ↓ MCP protocol (stdio)
@focusgts/firefly-services-mcp
    ↓
@adobe/firefly-apis | @adobe/photoshop-apis | @adobe/lightroom-apis
    ↓ HTTPS
firefly-api.adobe.io | image.adobe.io | ims-na1.adobelogin.com

Key architectural decisions:

ADR	Decision
001	Wrap Adobe SDKs; do not reimplement the API surface
002	Node.js + TypeScript + stdio transport
003	Single-credential-per-server-instance for v0.1
004	Storage references: triple-mode input (`upload_id` \| `url` \| `path`), dual-mode output (URL only or inlined bytes)
005	Tool naming: `<product>_<action>_<object>` snake_case

Full PRD: docs/PRD.md.

Two storage-reference models. Firefly tools take an image-reference object — exactly one of upload_id (an id from firefly_upload_image), url (a pre-signed GET URL on allow-listed cloud storage), or path (a local file the tool auto-uploads). The Photoshop and Lightroom tools instead take pre-signed URL strings directly — input_url (GET) and output_url (PUT to your own bucket) — because those Adobe APIs write results to caller-supplied storage rather than hosting them. Don't mix the two shapes.

Development

git clone https://github.com/Focus-GTS/firefly-services-mcp.git
cd firefly-services-mcp
npm install

# Type-check
npm run lint

# Run the server in dev mode (uses tsx, no build step)
FIREFLY_SERVICES_CLIENT_ID=<id> FIREFLY_SERVICES_CLIENT_SECRET=<secret> npm run dev

# Unit tests (mocked SDKs)
npm test

# Mocked integration tests (HTTP-layer mocks via msw)
npm run test:integration:mocked

# Live integration tests (real Adobe API — needs valid credentials)
npm run test:integration:live

# Build for production
npm run build

Smoke-test the protocol

The fastest way to verify the server is working end-to-end:

INIT='{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke-test","version":"0"}}}'
LIST='{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

( printf '%s\n%s\n%s\n' "$INIT" '{"jsonrpc":"2.0","method":"notifications/initialized"}' "$LIST"; sleep 1 ) \
  | FIREFLY_SERVICES_CLIENT_ID=dummy FIREFLY_SERVICES_CLIENT_SECRET=dummy npm run dev

You should see two JSON-RPC responses on stdout — the second one lists all registered tools.

Trademarks and independence

This repository is independently developed and maintained by FocusGTS.

"Adobe", "Adobe Firefly", "Adobe Firefly Services", "Photoshop", "Lightroom", "InDesign", "Creative Cloud", "Adobe Express", "Adobe Sensei", "GenStudio", and "Adobe Stock" are trademarks or registered trademarks of Adobe Inc. in the United States and/or other countries.
"Claude", "Claude Code", and "Model Context Protocol" are trademarks or service marks of Anthropic, PBC.
These trademarks are used under nominative fair use solely to identify the products this MCP server interoperates with.
This repository is not sponsored, endorsed, affiliated with, or supported by Adobe Inc. or Anthropic, PBC.

See NOTICE for the full trademark, attribution, and no-warranty statement.

License

Apache License 2.0. See LICENSE and NOTICE.

Distributed on an "AS IS" basis, without warranties or conditions of any kind. Endpoint paths, parameter shapes, and rate limits may change as Adobe evolves its APIs; verify against current official Adobe documentation before relying on any specific behavior.

Related projects

focusgts/firefly-services-skills — Companion Claude Code skills documenting the Firefly Services workflow patterns. The skills repo's catalog keeps an up-to-date count and index.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
examples		examples
scripts		scripts
src		src
test		test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
NOTICE		NOTICE
README.md		README.md
SECURITY.md		SECURITY.md
agentdb.rvf.lock		agentdb.rvf.lock
glama.json		glama.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Navigation Menu

Uh oh!

Repository files navigation

Firefly Services MCP Server

See it in action

Status

What this is

Install

Option 1 — From source (for development)

Option 2 — From npm (recommended)

Required environment variables

Tools (v0.2 surface — 19 tools)

Firefly (9)

Photoshop API (6)

Lightroom API (4)

Architecture

Development

Smoke-test the protocol

Trademarks and independence

License

Related projects

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Firefly Services MCP Server

See it in action

Status

What this is

Install

Option 1 — From source (for development)

Option 2 — From npm (recommended)

Required environment variables

Tools (v0.2 surface — 19 tools)

Firefly (9)

Photoshop API (6)

Lightroom API (4)

Architecture

Development

Smoke-test the protocol

Trademarks and independence

License

Related projects

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages