@focusgts/firefly-services-mcp

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.0 — 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): 17 of 19 tools live-validated end-to-end.

Surface	Tools	Status
Firefly	9	All 9 live-validated end-to-end against the real API (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) — each wrote a real result to a caller-owned bucket
Photoshop API	6	4 live-validated via GCS (document-manifest, edit-text, smart-object-replace, apply-edits). remove_background is blocked by an Adobe-side Sensei cutout outage (persistent 502, not a client issue); apply_actions is pending a real .atn action fixture

The Photoshop and Lightroom APIs, by Adobe's design, do not host outputs — the caller supplies a writable pre-signed output_url (S3 / Azure / GCS). The two remaining tools are gated on an external dependency (Adobe's Sensei service) and a binary .atn fixture respectively — not on the server. 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.

Copyright 2026 FocusGTS.

---

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.