alisaitteke/photoshop-mcp

참고: 이 프로젝트는 비공식적이며 커뮤니티에서 유지 관리되는 프로젝트로, Adobe Inc.와 관련이 없으며 공식적으로 보증되지 않습니다.

Claude 및 Cursor와 같은 AI 어시스턴트가 Adobe Photoshop 프로그램을 프로그래밍 방식으로 제어할 수 있게 해주는 Model Context Protocol (MCP) 서버입니다. 이를 통해 IDE에서 작업하는 동안 자연어 명령을 사용하여 디자인을 생성하고, 이미지를 조작하며, Photoshop 워크플로를 자동화할 수 있습니다.

이것을 Claude Desktop이나 Cursor에 연결하고 싶지 않으신가요? 동일한 패키지에 완전히 로컬에서 작동하는 웹 UI가 포함되어 있어, AI 모델과 채팅하며 이 MCP 서버를 통해 Photoshop을 구동할 수 있습니다.

npx -p @alisaitteke/photoshop-mcp photoshop-mcp-ui

끝입니다. 로컬 서버가 127.0.0.1 (무작위 무료 포트)에서 시작되며 기본 브라우저에서 채팅 UI가 자동으로 열립니다.

처음 실행 시 다음 중 하나를 선택하세요 — 본인의 API 키를 직접 준비해야 합니다:

제공업체 (Provider)	모델 (Models)	키 발급 (Get a key)
Anthropic	Claude Sonnet / Opus / Haiku	console.anthropic.com
OpenAI	GPT-5, GPT-4.1, o-series	platform.openai.com
Google	Gemini 2.5 Pro / Flash / Flash-Lite	aistudio.google.com
OpenRouter	모든 제공업체의 100개 이상의 모델	openrouter.ai

• 제공업체를 선택하고 API 키를 붙여넣으세요.
• 키는 제공업체를 통해 검증된 후 ~/.photoshop-mcp/data.db (SQLite, chmod 600)에 로컬로 저장됩니다. 키는 절대 사용자의 기기를 벗어나지 않습니다.
• 자연어 프롬프트를 입력하세요. UI는 모델의 응답을 스트리밍하고, Photoshop 도구 호출 (tool calls)을 실시간으로 실행하며, 각 도구 호출을 검사 가능한 카드(입력 + 결과)로 렌더링합니다.
• 모델 선택기에서 언제든지 제공업체나 모델을 전환할 수 있습니다 — 채팅, 비용 및 도구 기록은 세션 간에 유지됩니다.

photoshop-mcp-ui [--port 5174] [--host 127.0.0.1] [--no-open]

• 에이전트(Agent)는 Photoshop MCP 도구로만 제한됩니다 — 내장된 셸(Shell), 파일(File) 및 웹(Web) 도구는 비활성화됩니다.
• 기술 스택(Tech stack): 프론트엔드는 Vue 3 + Tailwind v4 + shadcn-vue를 사용하며, 백엔드는 Hono + Vercel AI SDK를 사용합니다. 에이전트 루프(Agent loop)는 STDIO를 통해 동일한 Photoshop MCP 서버와 통신하며, 이는 IDE 통합과 동일한 코드 경로를 따릅니다.

이 MCP 서버가 구성되었을 때 AI 어시스턴트(Claude, Cursor 등)와 함께 사용할 수 있는 프롬프트(Prompt) 예시는 다음과 같습니다:

🎨 기본 디자인 생성 (Basic Design Creation)

RGB 색상 모드로 1920x1080 Photoshop 문서를 생성해줘.
연한 파란색 배경 레이어를 추가하고 RGB(240, 248, 255)로 채워줘.
64pt 크기의 중앙 정렬된 텍스트 "Welcome"을 추가해줘.
...

🖼️ 스톡 이미지 디자인 (Pexels MCP 사용 시)

Pexels에서 "mountain sunset" 이미지를 검색해줘.
1920x1080 Photoshop 문서를 생성해줘.
다운로드한 이미지를 배치하고 캔버스 전체를 채우도록 크기를 맞춰줘.
...

✨ 사진 보정 (Photo Enhancement)

데스크탑에 있는 photo.jpg를 Photoshop에서 열어줘.
자동 레벨(Auto levels)과 자동 대비(Auto contrast)를 적용해줘.
언샤프 마스크(Unsharp mask)를 적용해줘 (양 120%, 반경 1.5, 임계값 0).
...

🎭 레이어 효과 및 블렌딩 (Layer Effects & Blending)

1200x800 문서를 생성해줘.
"Background"라는 이름의 새 레이어를 추가하고 RGB(50, 50, 50)로 채워줘.
logo.png를 (100, 100) 위치에 배치해줘.
...

📝 텍스트 포스터 디자인 (Text Poster Design)

1080x1350 세로형 문서(Instagram 스토리 크기)를 생성해줘.
레이어를 추가하고 그라데이션 느낌의 색상인 RGB(120, 40, 200)로 채워줘.
(540, 300) 위치에 96pt 크기로 "SUMMER" 텍스트를 추가해줘.
...

🎬 일괄 처리 (Batch Processing)

image1.jpg를 열어줘.
1920x1080 크기로 조정해줘.
자동 대비(Auto contrast)를 적용해줘.
...

🖌️ 창의적 조작 (Creative Manipulation)

2000x2000 정사각형 문서를 생성해줘.
abstract-pattern.jpg를 배치하고 문서에 맞춰 채워줘.
레이어를 복제해줘.
...

🎯 고급 워크플로우 (Advanced Workflow)

인쇄용으로 300 DPI의 3000x2000 문서를 생성해줘.
hero-image.jpg를 배치하고 캔버스에 맞춰 채워줘.
이미지 레이어를 복제해줘.
...

🔄 액션 사용 (Using Actions)

my-photo.jpg를 열어줘.
"My Actions" 세트에 있는 "Vintage Look" 액션을 실행해줘.
밝기를 -10만큼 조절해서 약간 어둡게 만들어줘.
...

⚡ 커스텀 스크립트 실행 (Custom Script Execution)

다음 커스텀 ExtendScript 코드를 실행해줘:
app.beep();
alert('Processing started!');

⏮️ 실행 취소/다시 실행 작업 (Undo/Redo Operations)

활성 레이어에 15px 가우시안 흐림 효과 (Gaussian blur)를 적용해줘.
[결과 대기]
사실, 흐림 효과가 너무 심해. 실행 취소(Undo)해줘.
...

또는:

어떤 작업들이 수행되었는지 확인하기 위해 히스토리 상태 (history states)를 가져와줘.
마지막 3개의 작업을 실행 취소(Undo)해줘.
한 단계를 다시 실행(Redo)해서 작업 하나를 복구해줘.

• ✅
  Windows 및 macOS 모두 지원 - ✅
  Photoshop 2012-2025+ 지원 - ✅
  ExtendScript API: AppleScript/COM 자동화를 통한 범용 호환성 - ✅
  자동 감지 (Auto-Detection): 시스템에서 Photoshop 설치 경로를 자동으로 찾음 - ✅
  50개 이상의 도구: 포괄적인 Photoshop 자동화 - ✅
  문서 관리 (Document Management): 문서 생성, 열기, 저장, 닫기, 자르기 - ✅
  레이어 작업 (Layer Operations): 레이어 생성, 삭제, 복제, 병합, 변형 - ✅
  레이어 속성 (Layer Properties): 불투명도 (Opacity), 블렌드 모드 (blend modes), 가시성 (visibility), 잠금 (locking) - ✅
  텍스트 서식 (Text Formatting): 글꼴, 크기, 색상, 정렬 제어 - ✅
  이미지 배치 (Image Placement): 이미지 배치, 파일 열기, 문서에 맞춤 - ✅
  필터 (Filters): 가우시안 흐림 효과 (Gaussian Blur), 샤픈 (Sharpen), 노이즈 (Noise), 모션 블러 (Motion Blur) - ✅
  색상 조정 (Color Adjustments): 밝기/대비 (Brightness/Contrast), 색상/채도 (Hue/Saturation), 자동 레벨/대비 (Auto Levels/Contrast) - ✅
  선택 및 마스크 (Selections & Masks): 사각형 선택 (Rectangular selections), 레이어 마스크 (layer masks) - ✅
  히스토리 제어 (History Control): 실행 취소/다시 실행 (Undo/Redo) 작업, 히스토리 상태 보기 - ✅
  액션 (Actions): 기록된 액션 재생, 커스텀 스크립트 실행 - ✅
  자동 래스터화 (Auto-Rasterize): 필터 적용 시 필요한 경우 레이어를 자동으로 변환 - ✅
  컨텍스트 추적 (Context Tracking): AI의 컨텍스트 인지(context awareness)를 위해 각 작업 후 문서/레이어 상태를 반환

설치가 필요 없습니다! MCP 클라이언트를 구성하기만 하면 됩니다:

npx @alisaitteke/photoshop-mcp

git clone https://github.com/alisaitteke/photoshop-mcp.git
cd photoshop-mcp
npm install
...

Cursor 설정(.cursor/config.json 또는 워크스페이스 설정)에 추가하세요:

{
"mcpServers": {
"photoshop": {
...

Claude Desktop 설정(~/Library/Application Support/Claude/claude_desktop_config.json)에 추가하세요.

macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json 또는 Windows의 경우 %APPDATA%\Claude\claude_desktop_config.json에 추가하세요.

{
"mcpServers": {
"photoshop": {
...

PHOTOSHOP_PATH
: (선택 사항) 사용자 정의 Photoshop 설치 경로를 지정합니다.

LOG_LEVEL
: 로깅 레벨 (0=DEBUG, 1=INFO, 2=WARN, 3=ERROR)

Photoshop과의 연결을 테스트합니다.

// 예시: Photoshop에 접근 가능한지 확인
photoshop_ping()

Photoshop 버전 정보를 가져옵니다.

// 예시: 버전 상세 정보 가져오기
photoshop_get_version()

새로운 Photoshop 문서를 생성합니다.

매개변수 (Parameters):

width
(number, 필수): 픽셀 단위의 문서 너비

height
(number, 필수): 픽셀 단위의 문서 높이

resolution
(number, 선택 사항): DPI 해상도 (기본값: 72)

colorMode
(string, 선택 사항): 색상 모드 - RGB, CMYK 또는 Grayscale (기본값: RGB)

// 예시: 1920x1080 RGB 문서 생성
photoshop_create_document({
width: 1920,
...

활성 문서(active document)에 대한 정보를 가져옵니다.

// 예시: 현재 문서 상세 정보 가져오기
photoshop_get_document_info()

활성 문서를 저장합니다.

매개변수 (Parameters):

path
(string, 필수): 저장할 전체 경로

format
(string, 선택 사항): PSD, JPEG 또는 PNG (기본값: PSD)

quality
(number, 선택 사항): JPEG 품질 1-12 (기본값: 8)

// 예시: JPEG로 저장
photoshop_save_document({
path: "/Users/username/Desktop/output.jpg",
...

활성 문서를 닫습니다.

매개변수 (Parameters):

save
(boolean, 선택 사항): 닫기 전에 저장 여부 (기본값: false)

// 예시: 저장하지 않고 닫기
photoshop_close_document({ save: false })

새로운 레이어 (layer)를 생성합니다.

매개변수 (Parameters):

name
(string, 선택 사항): 레이어 이름

// 예시: 이름이 지정된 레이어 생성
photoshop_create_layer({ name: "Background" })

활성 레이어를 삭제합니다.

// 예시: 현재 레이어 삭제
photoshop_delete_layer()

텍스트 레이어를 생성합니다.

매개변수 (Parameters):

text
(string, 필수): 텍스트 내용

x
(number, 선택 사항): 픽셀 단위의 X 좌표 (기본값: 100)

y
(number, 선택 사항): 픽셀 단위의 Y 좌표 (기본값: 100)

fontSize

(number, 선택 사항): 포인트(points) 단위의 글꼴 크기 (기본값: 24)

// 예시: 텍스트 레이어 생성
photoshop_create_text_layer({
text: "Hello World",
...

활성 레이어(active layer)를 단색으로 채웁니다.

매개변수 (Parameters):

red

(number, 필수): 빨간색 성분 (0-255)

green

(number, 필수): 초록색 성분 (0-255)

blue

(number, 필수): 파란색 성분 (0-255)

// 예시: 파란색으로 채우기
photoshop_fill_layer({
red: 0,
...

활성 문서(active document)의 모든 레이어 목록을 가져옵니다.

// 예시: 모든 레이어 목록 가져오기
photoshop_get_layers()

활성 레이어의 불투명도(opacity)를 설정합니다.

매개변수 (Parameters):

opacity

(number, 필수): 불투명도 값 (0-100)

// 예시: 불투명도를 75%로 설정
photoshop_set_layer_opacity({ opacity: 75 })

활성 레이어의 블렌드 모드(blend mode)를 설정합니다.

매개변수 (Parameters):

blendMode

(string, 필수): 블렌드 모드 (NORMAL, MULTIPLY, SCREEN, OVERLAY 등)

// 예시: 블렌드 모드를 multiply로 설정
photoshop_set_layer_blend_mode({ blendMode: "MULTIPLY" })

사용 가능한 블렌드 모드: NORMAL, DISSOLVE, DARKEN, MULTIPLY, COLORBURN, LINEARBURN, DARKERCOLOR, LIGHTEN, SCREEN, COLORDODGE, LINEARDODGE, LIGHTERCOLOR, OVERLAY, SOFTLIGHT, HARDLIGHT, VIVIDLIGHT, LINEARLIGHT, PINLIGHT, HARDMIX, DIFFERENCE, EXCLUSION, SUBTRACT, DIVIDE, HUE, SATURATION, COLOR, LUMINOSITY

활성 레이어를 보이게 하거나 숨깁니다.

매개변수 (Parameters):

visible

(boolean, 필수): 가시성 상태

// 예시: 레이어 숨기기
photoshop_set_layer_visibility({ visible: false })

활성 레이어를 잠그거나 잠금을 해제합니다.

매개변수 (Parameters):

locked

(boolean, 필수): 잠금 상태

// 예시: 레이어 잠그기
photoshop_set_layer_locked({ locked: true })

활성 레이어의 이름을 변경합니다.

매개변수 (Parameters):

name

(string, 필수): 새로운 레이어 이름

// 예시: 레이어 이름 변경
photoshop_rename_layer({ name: "Hero Image" })

활성 레이어를 복제합니다.

매개변수 (Parameters):

newName

(string, 선택 사항): 복제된 레이어의 이름

// 예시: 새 이름으로 레이어 복제
photoshop_duplicate_layer({ newName: "Background Copy" })

모든 보이는 레이어를 하나로 병합합니다.

// 예시: 보이는 레이어 병합
photoshop_merge_visible_layers()

모든 레이어를 하나의 배경 레이어로 병합(Flatten)합니다.

// 예시: 이미지 병합 (Flatten)
photoshop_flatten_image()

활성 레이어를 래스터화(Rasterize)합니다 (텍스트/스마트 오브젝트를 일반 레이어로 변환).

// 예시: 레이어 래스터화
photoshop_rasterize_layer()

활성 레이어를 다른 레이어에 상대적으로 이동합니다.

매개변수 (Parameters):

targetLayerName

(string, 필수): 참조할 레이어의 이름

position

(string, 필수): ABOVE, BELOW, TOP, 또는 BOTTOM

// 예시: "Background" 레이어 위로 이동
photoshop_move_layer_to_position({
targetLayerName: "Background",
...

활성 레이어를 레이어 스택의 맨 위로 이동합니다.

// 예시: 맨 위로 이동
photoshop_move_layer_to_top()

활성 레이어를 레이어 스택의 맨 아래로 이동합니다.

// 예시: 맨 아래로 이동
photoshop_move_layer_to_bottom()

활성 레이어를 한 단계 위로 이동합니다.

// 예시: 위로 이동
photoshop_move_layer_up()

활성 레이어를 한 단계 아래로 이동합니다.

// 예시: 아래로 이동
photoshop_move_layer_down()

종횡비(Aspect Ratio)를 유지하면서 활성 레이어를 문서 캔버스에 맞게 크기를 조정합니다.

매개변수 (Parameters):

fillDocument

(boolean, 선택 사항): true인 경우 전체 캔버스를 채웁니다 (크롭될 수 있음). false인 경우 캔버스 내에 맞춥니다 (여백이 생길 수 있음). 기본값: false

// 예시: 레이어를 캔버스 내에 맞춤
photoshop_fit_layer_to_document({ fillDocument: false })
// 예시: 전체 캔버스 채우기 (필요 시 크롭)
...

활성 레이어를 백분율(Percentage)로 크기 조정합니다.

매개변수 (Parameters):

scalePercent

(number, 필수): 크기 조정 백분율 (예: 50%의 경우 50, 200%의 경우 200)

centerAnchor

(boolean, 선택 사항): 중앙에서 크기 조정 (true) 또는 왼쪽 상단에서 크기 조정 (false). 기본값: true

// 예시: 150%로 크기 조정
photoshop_scale_layer({
scalePercent: 150,
...

활성 레이어를 지정된 오프셋(Offset)만큼 이동합니다.

매개변수 (Parameters):

deltaX

(number, 필수): 픽셀 단위의 가로 오프셋 (Horizontal offset)

deltaY

(number, 필수): 픽셀 단위의 세로 오프셋 (Vertical offset)

// 예시: 레이어를 오른쪽으로 100px, 아래로 50px 이동
photoshop_move_layer({
deltaX: 100,
...

활성 레이어를 회전시킵니다.

매개변수 (Parameters):

degrees

(number, 필수): 도(degrees) 단위의 회전 각도 (양수 = 시계 방향)

// 예시: 시계 방향으로 45도 회전
photoshop_rotate_layer({ degrees: 45 })

활성 레이어에 가우시안 블러 (Gaussian Blur) 필터를 적용합니다.

매개변수 (Parameters):

radius

(number, 필수): 픽셀 단위의 블러 반경 (0.1-250)

// 예시: 10px 블러 적용
photoshop_apply_gaussian_blur({ radius: 10 })

언샤프 마스크 (Unsharp Mask, 선명하게 하기) 필터를 적용합니다.

매개변수 (Parameters):

amount

(number, 필수): 퍼센트(%) 단위의 선명도 양 (1-500)

radius

(number, 필수): 픽셀 단위의 반경 (0.1-250)

threshold

(number, 선택 사항): 임계값 레벨 (0-255, 기본값: 0)