Skip to main content
Glama
alisaitteke

Photoshop MCP Server

by alisaitteke
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

photoshop_recipe_batch_watermark

Batch watermark every image in a folder with text or a logo and export watermarked JPEGs, replacing the record-an-action batch workflow.

Instructions

Apply a text or logo watermark to every image in a folder and export watermarked JPEGs. Replaces the clunky record-an-action + File > Automate > Batch workflow.

Use when: the user wants to watermark many photos at once (copyright text, studio logo). Do NOT use when: watermarking a single open document (use photoshop_create_text_layer / photoshop_place_image directly) or removing watermarks (not supported).

Returns: { ok, summary, output_paths, details: { processed, failed: [{ file, error }] } }. Files that fail are skipped, not fatal.

Preconditions: assets_dir exists; either text or logo_path given. No active document required. Side effects: writes one JPEG per source image; source files are never modified.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
textNoWatermark text (e.g. "© Jane Doe 2026"). White, semi-transparent. Required unless logo_path is given.
opacityNoWatermark layer opacity 0-100. Default 40.
qualityNoJPEG quality on the Photoshop 1-12 scale. Default 10.
positionNoWatermark placement. Default bottom_right.bottom_right
font_sizeNoText watermark size in pixels. Default 0 = auto (4% of each image height, min 8px).
logo_pathNoAbsolute path to a logo image (transparent PNG recommended). Required unless text is given. If both are given, text wins.
margin_pxNoDistance from the chosen edge(s) in pixels. Default 24 (ignored for center).
scale_pctNoLogo watermark width as a percentage of image width (1-100). Default 15. Logo mode only.
assets_dirYesAbsolute path to the folder of images to watermark. Subdirectories are NOT recursed. Allowed extensions: jpg/jpeg/png/tif/tiff/webp.
document_idYesPhotoshop document id from photoshop_get_state / photoshop_list_documents. Send null or 0 to use the active document. A positive number activates that document before the tool runs. When no document is open, a stale id does not block the call.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv1.7.33
    • changedInput schema / properties / document_id / description
      Previous value: -"Photoshop document id from photoshop_get_state / photoshop_list_documents. Send null to use the active document. A number activates that document before the tool runs."New value: +"Photoshop document id from photoshop_get_state / photoshop_list_documents. Send null or 0 to use the active document. A positive number activates that document before the tool runs. When no document is open, a stale id does not block the call."
  2. Changed4 schema fields changedv1.7.32
    • addedInput schema / additionalProperties
      Added value: +false
    • changedInput schema / properties / document_id / description
      Previous value: -"Optional Photoshop document id from photoshop_get_state / photoshop_list_documents. When set, the tool activates that document before running so a UI tab switch cannot retarget the edit."New value: +"Photoshop document id from photoshop_get_state / photoshop_list_documents. Send null to use the active document. A number activates that document before the tool runs."
    • changedInput schema / properties / document_id / type
      Previous value: -"number"New value: +[
+  "number",
+  "null"
+]
    • changedInput schema / required
      Previous value: -[
-  "assets_dir"
-]New value: +[
+  "assets_dir",
+  "document_id"
+]
  3. First observedv0.1.0

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare this is a write operation (readOnlyHint=false) that is non-destructive and non-idempotent; the description goes further by stating side effects ('writes one JPEG per source image; source files are never modified'), failure semantics ('Files that fail are skipped, not fatal'), and preconditions (assets_dir exists; text or logo_path given). This is strong disclosure. It stops short of covering overwrite behavior for existing output files or output naming/location, which keeps it off a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose sentence followed by labeled sections (Use when / Do NOT use when / Returns / Preconditions / Side effects) with no filler. Every line carries actionable information for an agent.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description supplies the return shape ({ ok, summary, output_paths, details: { processed, failed } }), preconditions, side effects, and failure handling. For a 10-parameter batch tool with full annotation coverage, nothing an agent needs to invoke it correctly is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and each of the 10 parameters already carries a rich inline description (ranges, defaults, text-vs-logo precedence). The description adds only the summary precondition 'either text or logo_path given,' so the baseline 3 applies — the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb+resource+scope: 'Apply a text or logo watermark to every image in a folder and export watermarked JPEGs.' It also positions itself against the legacy Batch workflow, making it clearly distinct from single-document siblings like photoshop_create_text_layer and photoshop_place_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit 'Use when' (many photos at once, copyright text or studio logo) and 'Do NOT use when' (single open document, watermark removal) clauses, naming the alternative sibling tools directly. Routing is unambiguous.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools