두 디자인 도구, 같은 프로토콜을 바라보는 두 철학이 있다. Penpot은 AI 에이전트에게 작은 도구 상자와 JavaScript 런타임을 건네고, Figma는 길고 전문화된 메뉴를 제공한다. 이 차이는 의도된 것이다.
Penpot과 Figma의 차이: 전문 메뉴보다 범용 실행기
Penpot의 Model Context Protocol 서버는 Figma의 약 24개 이름 붙은 액션 카탈로그와 달리 execute_code, high_level_overview, penpot_api_info, export_shape, import_image라는 정확히 다섯 가지 도구만 노출한다 . 핵심은 execute_code다. 에이전트가 JavaScript를 작성하면 Penpot이 에디터의 플러그인 샌드박스 안에서 이를 실행하고, 전체 Plugins API에 접근할 수 있다. 그래서 전문 서버라면 여러 도구로 나눌 작업을 하나의 엔드포인트가 포괄한다 .
아래 스니펫은 검증 및 실행을 거쳐 두 카탈로그의 개수를 직접 센 것이다.
penpot_tools = [
"execute_code",
"high_level_overview",
"penpot_api_info",
"export_shape",
"import_image",
]
figma_tools = [
"add_code_connect_map",
"create_new_file",
"download_assets",
"generate_diagram",
"generate_figma_design",
"get_code_connect_map",
"get_code_connect_suggestions",
"get_context_for_code_connect",
"get_design_context",
"get_figjam",
"get_libraries",
"get_metadata",
"get_motion_context",
"get_screenshot",
"get_shader_effect",
"get_shader_fill",
"get_variable_defs",
"list_shader_effects",
"list_shader_fills",
"search_design_system",
"send_code_connect_mappings",
"upload_assets",
"use_figma",
"whoami",
]
print(f"Penpot MCP: {len(penpot_tools)} tools")
print(f"Figma MCP: {len(figma_tools)} tools (~two dozen)")
print(f"Figma exposes {len(figma_tools) / len(penpot_tools):.1f}x as many tools.")Penpot의 논리는 컨텍스트 절약이다. 도구 스키마가 적으면 실제 호출이 일어나기 전에 모델의 컨텍스트 창을 덜 차지한다. Penpot은 큰 도구 세트가 작은 모델 컨텍스트의 10~15%를 소비할 수 있다고 주장하지만, 이 수치는 Penpot 자체의 주장일 뿐 공개된 제3자 벤치마크로 뒷받침되지는 않는다. 따라서 측정 결과가 아니라 설계 근거로 봐야 한다 . 라이선스도 다르다. Penpot MCP는 MPL-2.0이고, 셀프 호스팅이 가능하며, 페이월이 없다고 홍보된다. 반면 Figma는 고급 Dev Mode 검사와 MCP 서버를 유료 좌석에 연결하고, 무료에서는 월 20회 도구 호출, 상위 티어에서는 하루 최대 600회까지 단계별 rate limit을 둔다 . 정식 코드는 develop 브랜치의 /mcp 아래 penpot/penpot(약 5.8만 stars)에 있다. 독립 저장소였던 penpot/penpot-mcp는 2026년 2월 3일 아카이브되어 본 저장소로 합쳐졌고, npm 패키지 @penpot/mcp로도 배포된다 .
연결 전에 준비할 것
에이전트가 Penpot 파일을 조회하려면 세 가지가 필요하다. Penpot 인스턴스, MCP를 지원하는 클라이언트, 그리고 연결 방식이다. 인스턴스는 penpot.app의 Penpot 클라우드일 수도 있고 Docker, Kubernetes, Elestio, 온프레미스 방식으로 배포한 셀프 호스팅 환경일 수도 있다. MPL-2.0 라이선스이며 MCP 서버 사용에 비용 제한은 없다 . 서버가 명시적으로 클라이언트 독립적인 HTTP 기반이므로, HTTP로 MCP를 말할 수 있는 클라이언트라면 동작한다. 문서에는 Cursor, Claude Code, GitHub Copilot을 붙인 VS Code, Codex, OpenCode가 안내되어 있다 .
그다음 방식을 고른다. 원격 모드는 Node.js가 필요 없다. Your account → Integrations → MCP Server에서 계정당 MCP 키 하나를 생성하며, 이 키는 한 번만 표시되고 복구할 수 없다 . 로컬 모드는 Node.js v20 또는 v22가 필요하고 npx @penpot/mcp@stable을 실행한다. 기본값은 HTTP가 localhost:4401/mcp, SSE가 localhost:4401/sse, WebSocket이 4402번 포트다 .
Cursor 또는 Claude Code에 Penpot MCP 연결하기
방식을 정했다면 세 단계로 에이전트를 라이브 파일에 연결할 수 있다. 첫째, MCP 키를 생성한다. Penpot UI에서 Your account → Integrations → MCP Server로 이동하면 키가 정확히 한 번 표시되며 복구할 수 없다. 사용자당 한 번에 하나의 키만 존재한다 . 키를 잃어버렸다면 폐기하고 다시 생성해야 한다. 다만 연결된 모든 에이전트 설정은 새 URL을 각각 붙여넣기 전까지 끊기므로, 재생성은 로컬 수정이 아니라 전체 연결 환경 업데이트로 다뤄야 한다.
둘째, 클라이언트에 서버 URL을 등록한다. 원격 모드에서는 Cursor나 Claude Code의 MCP 서버 필드에 https://<your-penpot-domain>/mcp/stream?userToken=YOUR_MCP_KEY를 붙여넣는다. 서버는 HTTP 기반의 클라이언트 독립 방식이며 Cursor, Claude Code, VS Code/Copilot, Codex/OpenCode 모두 문서화된 연동을 제공한다 . 로컬 모드에서는 npm 패키지를 실행하고 클라이언트가 대신 localhost:4401/mcp를 바라보게 한다. 활성 브라우저 세션을 사용하므로 토큰은 필요 없다 .
셋째, Penpot 파일을 열고 high_level_overview를 호출한다. 에이전트가 페이지 이름, 컴포넌트 수, 색상 및 타이포그래피 토큰 그룹을 반환하는지 확인한다. 구조가 보이면 짧은 JavaScript 표현식 형태의 표적 execute_code 호출을 보내라. 에디터가 플러그인 샌드박스 안에서 이를 실행하므로, 스크린샷이 아니라 파일에서 직접 특정 토큰 값이나 컴포넌트 속성을 가져올 수 있다 .
방식을 가르는 핵심 기능 차이가 하나 있다. 로컬 모드는 로컬 경로에서 전체 export_shape와 import_image를 추가로 제공하지만, 원격 모드는 둘 다 제한되고 로컬 파일 시스템 접근도 제공하지 않는다 . 2026년 8월 기준 문서에는 호스팅 방식과 로컬 방식에 관한 표현 불일치가 일부 남아 있으므로, 워크플로를 연결하기 전 현재의 공식 상태는 help.penpot.app/mcp에서 교차 확인하라.
느리고 비싸며 덮어쓰기 위험까지: Penpot이 경고하는 점
쓰기 권한은 기본적으로 실시간으로 작동한다. 연결된 에이전트는 현재 포커스된 페이지에서 객체를 생성, 이름 변경, 이동, 삭제, 스타일 변경할 수 있으므로, Penpot은 에이전트의 동작과 플러그인이 실행되는 권한 범위를 모두 검토하기 전까지는 중요한 프로덕션 파일에서 MCP를 사용하지 말라고 권고한다 . 에이전트가 실제로 파일에 어떤 작업을 하는지 평가하는 동안에는 작고 되돌리기 쉬운 작업을 우선하는 편이 좋다.
Penpot은 한계도 분명히 말한다. MCP로 디자인을 자율 생성하는 방식은 느리고, 비싸며, 오류가 나기 쉽다 . 오래 쓸 만한 활용처는 전체 디자인 자동 조종이 아니라 더 나은 코드 출력을 위한 구조화된 컨텍스트다. 예를 들면 CSS 변수 생성, 컴포넌트 스캐폴딩, Storybook 정합성 맞추기 같은 작업이다.
"The MCP server describes tools as model-controlled functions and recommends clear UI, visible invocation indicators, and human confirmation before write actions" — Model Context Protocol tools specification, 2025-06-18 (source: modelcontextprotocol.io).
이 지침은 Penpot 자체의 권고와도 맞닿아 있다. 모델이 제어하는 쓰기 작업에는 사람이 계속 개입해야 한다는 것이다 . 디자인-투-코드 출력에 대해 검증된 정확도 수치는 없다. 품질은 모델, 프롬프트, 파일 복잡도, 권한에 따라 달라지므로, MCP가 생성한 코드는 검토 없이 프로덕션에 바로 쓸 수 있는 것으로 취급해서는 안 된다.
Penpot 2.14-2.17의 W3C DTCG 토큰: 지금 코드로 읽을 수 있는 것
MCP와 디자인 토큰이 만나는 지점은 Plugins API다. Penpot 2.14에서 토큰 값 접근이 열렸다. 2026년 3월 17일 이후 커뮤니티에 공개된 이 업데이트는 외부 코드가 토큰을 프로그래밍 방식으로 읽고 쓸 수 있게 했으며, 릴리스 노트는 그 사용 주체를 명시적으로 언급한다.
"AI clients or Penpot MCP" can now work with tokens through the Plugins API — release notes, Penpot 2.14 (source: help.penpot.app).
값은 W3C Design Tokens Community Group 초안을 따른다. 색상, 타이포그래피, 간격, 그림자, 별칭, 값 안의 수식, 토큰 세트, 테마, JSON 가져오기/내보내기를 지원하며, 별도의 독점 동기화 플러그인은 필요 없다. 이 점이 Figma Variables와 대비된다 . 이후 릴리스에서는 워크플로가 더 다듬어졌다. 2.16(2026년 6월 2일)은 선택한 요소에서 숫자 토큰 바인딩을 드러냈고 , 2.17.0(2026년 7월 22일)은 여러 텍스트를 선택했을 때 타이포그래피 토큰 행, 전파 최적화, 토큰 양식 자동완성을 추가했다 .
실무에서 도착점은 execute_code다. 에이전트가 Plugins API를 통해 토큰 그룹을 열거하게 하고 , 이를 DTCG 형식 JSON으로 내보낸 다음 Storybook 설정, CSS 커스텀 속성 생성기, Tailwind 테마로 흘려보내면 된다. 디자인 패널에서 수동으로 복사해 붙여 넣을 필요가 없다. 이것이 구체적인 이점이다. 자율 디자인이 아니라, 코딩 에이전트가 필요할 때 조회할 수 있는 셀프 호스팅 가능하고 표준 기반인 토큰 피드다.
자주 묻는 질문
Penpot MCP 서버는 무료로 사용할 수 있나요?
네. Penpot은 Mozilla Public License 2.0으로 라이선스가 제공되며, MCP 서버에 대해 페이월이나 좌석별 제한을 두지 않습니다 . 원격 모드는 penpot.app에서 Penpot이 호스팅하고, 로컬 모드는 사용자의 컴퓨터에서 npm 패키지(npx @penpot/mcp@stable)로 실행됩니다 . 어느 쪽이든 Penpot 인스턴스 자체를 운영하는 비용 외에는 추가 비용이 없습니다. MCP 서버를 유료 좌석에 묶고 요금제별 속도 제한을 적용하는 Figma와 대비되는 지점입니다 .
Penpot MCP 키를 잃어버리면 어떻게 되나요?
키는 복구할 수 없고 한 번만 표시되므로, 잃어버린 키는 다시 확인할 수 없습니다. Your account → Integrations → MCP Server에서 해당 키를 폐기하고 새 키를 생성해야 합니다 . 사용자당 MCP 키는 한 번에 하나만 존재할 수 있으므로 , 키를 교체하면 기존의 모든 연결이 무효화됩니다. 다시 생성한 뒤에는 연결된 각 에이전트 설정에서 서버 URL의 userToken 값을 새 값으로 업데이트하세요. 로컬 모드는 활성 브라우저 세션을 사용하고 토큰이 필요 없기 때문에 이 문제를 피할 수 있습니다.
연결된 AI 에이전트가 Penpot 파일의 오브젝트를 덮어쓰거나 삭제할 수 있나요?
네. 쓰기 접근 권한은 기본적으로 켜져 있습니다. 연결된 에이전트는 현재 포커스된 페이지에서 오브젝트를 만들고, 이름을 바꾸고, 이동하고, 삭제하고, 스타일을 변경할 수 있습니다 . Penpot은 MCP를 중요한 프로덕션 파일과 분리해 두고, 에이전트 동작을 평가하는 동안에는 작고 되돌릴 수 있는 작업을 사용하라고 명시적으로 권고합니다 . 자율성을 넓히기 전에 플러그인 권한 범위를 검토하세요. MCP 도구 사양 자체도 모델이 제어하는 기능에 대해 호출 표시를 눈에 보이게 하고 사람의 확인을 받도록 권장합니다 .
Penpot의 토큰 형식은 Figma Variables와 어떻게 다른가요?
Penpot은 공개 W3C Design Tokens Community Group(DTCG) 초안 형식을 따르는 반면, Figma Variables는 독점 스키마를 사용합니다. Penpot 토큰은 변환 플러그인 없이 DTCG 호환 JSON으로 내보낼 수 있으며, 색상, 타이포그래피, 간격, 그림자, 별칭, 테마를 포함합니다 . Penpot 2.14부터 토큰은 Plugins API를 통해 읽고 쓸 수 있습니다. 릴리스 노트는 이제 토큰을 프로그래밍 방식으로 다룰 수 있는 외부 도구로 “AI clients or Penpot MCP”를 명시합니다 . MCP 에이전트는 execute_code를 통해 이 계층에 접근합니다.
Penpot MCP와 작동이 확인된 AI 코딩 클라이언트는 무엇인가요?
Penpot은 Cursor, Claude Code, GitHub Copilot을 사용하는 VS Code, Codex/OpenCode와의 통합을 문서화하고 있습니다 . 서버는 HTTP 전송을 통해 특정 클라이언트에 종속되지 않도록 설계되어 있으며, “any AI agent, any LLM you trust”와 연결할 수 있다고 설명하므로 HTTP 전송을 지원하는 MCP 클라이언트라면 특정 LLM 공급업체와 무관하게 작동해야 합니다 . 원격 모드는 로컬 모드보다 기능이 제한됩니다. 로컬 파일 시스템 접근이 없고 import_image 및 export_shape 기능도 제한되므로, 사용하는 클라이언트와 권한에 맞는 모드를 선택하세요 .
이 글이 도움이 되셨다면, 새 글이 올라올 때마다 이메일로 받아보세요.
