Penpot MCP Server

A comprehensive Model Context Protocol (MCP) server for Penpot, the open-source design platform. This server provides full access to Penpot's capabilities through 14 powerful tools covering projects, files, components, design tokens, exports, comments, teams, and more.

Features

• 🗂️ Project Management: Full CRUD operations for projects with file organization
• 📁 File Operations: Create, edit, duplicate, move files with version history
• 🧩 Component Library: Manage reusable components with instances, annotations, and stats
• 🎨 Design Tokens: Colors, typography with export to CSS/JSON/SCSS/Tailwind
• 📤 Asset Export: PNG, SVG, PDF, JPEG, WebP with multi-scale and batch support
• 💬 Comments & Reviews: Thread-based commenting with resolution tracking
• 👥 Team Collaboration: Team management, invitations, roles, and permissions
• 👤 Profile Management: User settings, notifications, recent files
• 📚 Library Sharing: Shared libraries, linking, publishing, and sync
• 🔍 Global Search: Search across files, objects, components, tokens
• 📊 Design Analysis: Design system audits, accessibility, duplicates detection

Architecture

penpot-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── server-core.ts        # MCP server implementation
│   ├── config.ts             # Configuration management
│   ├── logger.ts             # Logging utility
│   ├── api/
│   │   ├── client-factory.ts # API client factory (9 domain clients)
│   │   ├── base/             # Base API client & utilities
│   │   │   ├── base-client.ts
│   │   │   ├── error-handler.ts
│   │   │   ├── response-formatter.ts
│   │   │   └── index.ts
│   │   └── domains/          # Domain-specific API clients
│   │       ├── projects-api.ts   # Project CRUD, files, stats
│   │       ├── files-api.ts      # File operations, pages, objects
│   │       ├── components-api.ts # Components, instances, annotations
│   │       ├── tokens-api.ts     # Colors, typography, export
│   │       ├── exports-api.ts    # Asset export (PNG/SVG/PDF/etc)
│   │       ├── comments-api.ts   # Threads, comments, resolution
│   │       ├── team-api.ts       # Team management, invitations
│   │       ├── profile-api.ts    # User profile, settings
│   │       ├── library-api.ts    # Shared libraries, linking
│   │       └── index.ts
│   └── tools/
│       ├── tool-definitions.ts   # MCP tool schemas (14 tools)
│       ├── index.ts
│       └── orchestration/        # High-level orchestration tools
│           ├── projects.ts       # penpot_projects
│           ├── files.ts          # penpot_files
│           ├── components.ts     # penpot_components
│           ├── tokens.ts         # penpot_tokens
│           ├── exports.ts        # penpot_exports
│           ├── comments.ts       # penpot_comments
│           ├── team.ts           # penpot_team
│           ├── profile.ts        # penpot_profile
│           ├── library.ts        # penpot_library
│           ├── search.ts         # penpot_search
│           ├── analyze.ts        # penpot_analyze
│           ├── navigate.ts       # penpot_navigate (legacy)
│           ├── inspect.ts        # penpot_inspect (legacy)
│           ├── assets.ts         # penpot_assets (legacy)
│           ├── types.ts
│           └── index.ts
├── package.json
├── tsconfig.json
└── README.md

Installation

npm install
npm run build

Configuration

Create a .env file:

# Required: Penpot credentials
PENPOT_USERNAME=your-email@example.com
PENPOT_PASSWORD=your-password

# Optional: Custom Penpot instance URL (defaults to design.penpot.app)
PENPOT_API_URL=https://design.penpot.app/api

# Optional: Default project scope
PENPOT_PROJECT_ID=your-project-id

# Optional: Logging level
LOG_LEVEL=info

Usage with Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "penpot": {
      "command": "node",
      "args": ["/path/to/penpot-mcp/dist/index.js"],
      "env": {
        "PENPOT_USERNAME": "your-email@example.com",
        "PENPOT_PASSWORD": "your-password"
      }
    }
  }
}

Available Tools (14 Total)

Core Tools

Tool	Description
penpot_projects	Project management: list, create, rename, delete, duplicate, move
penpot_files	File operations: CRUD, pages, objects, tree, search, history
penpot_components	Component library: list, search, instances, create, delete, annotations
penpot_tokens	Design tokens: colors, typography, CRUD, export to CSS/JSON/SCSS/Tailwind
penpot_exports	Asset export: PNG, SVG, PDF, JPEG, WebP with batch and multi-scale
penpot_comments	Comment management: threads, replies, resolve, reopen
penpot_team	Team management: members, invitations, roles, permissions
penpot_profile	User profile: settings, notifications, recent files
penpot_library	Shared libraries: link, unlink, publish, sync
penpot_search	Global search: files, objects, components, tokens
penpot_analyze	Design analysis: design system, accessibility, duplicates

Legacy Tools (Backward Compatibility)

Tool	Description
penpot_navigate	Navigate projects, files, pages
penpot_inspect	Deep inspection of file structure
penpot_assets	Basic asset export

Tool Actions Reference

penpot_projects

Action	Description	Required Params
list	List all projects	-
get	Get project details	projectId
create	Create new project	name
rename	Rename project	projectId, name
delete	Delete project	projectId
duplicate	Duplicate project	projectId
move	Move to team	projectId, targetTeamId
files	List project files	projectId
stats	Project statistics	projectId

penpot_files

Action	Description	Required Params
get	Get file details	fileId
create	Create new file	projectId, name
rename	Rename file	fileId, name
delete	Delete file	fileId
duplicate	Duplicate file	fileId
move	Move to project	fileId, projectId
pages	List file pages	fileId
page	Get page objects	fileId, pageId
objects	Get page objects	fileId, pageId
object	Get specific object	fileId, pageId, objectId
tree	Get object tree	fileId, objectId
search	Search objects	fileId, query
analyze	Analyze structure	fileId
history	Version history	fileId
snapshot	Create/restore	fileId

penpot_components

Action	Description	Required Params
list	List components	fileId
get	Get component	fileId, componentId
search	Search components	fileId, query
instances	Get instances	fileId, componentId
structure	Get structure	fileId, componentId
create	Create component	fileId, objectId, name
delete	Delete component	fileId, componentId
rename	Rename component	fileId, componentId, name
annotate	Add annotation	fileId, componentId, annotation
stats	Component stats	fileId
detach	Detach instance	fileId, instanceId
reset	Reset instance	fileId, instanceId

penpot_tokens

Action	Description	Required Params
colors	List colors	fileId
color	Get color	fileId, colorId
create_color	Create color	fileId, name, color
update_color	Update color	fileId, colorId
delete_color	Delete color	fileId, colorId
typography	List typography	fileId
typography_style	Get style	fileId, styleId
create_typography	Create style	fileId, name
update_typography	Update style	fileId, styleId
delete_typography	Delete style	fileId, styleId
all	Get all tokens	fileId
search	Search tokens	fileId, query
export_css	Export as CSS	fileId
export_json	Export as JSON	fileId
export_scss	Export as SCSS	fileId
export_tailwind	Export Tailwind	fileId
stats	Token statistics	fileId

penpot_exports

Action	Description	Required Params
export	Export object	fileId, objectId, format
batch	Batch export	fileId, objectIds
page	Export page	fileId, pageId
file_pdf	Export as PDF	fileId
multi_scale	Multi-scale export	fileId, objectId, scales
multi_format	Multi-format export	fileId, objectId, formats
list	List exportable	fileId
settings	Export settings	fileId, objectId
download	Download export	exportId
formats	Supported formats	-

penpot_comments

Action	Description	Required Params
list	List threads	fileId
thread	Get thread	threadId
create_thread	Create thread	fileId, pageId, content
add	Add comment	threadId, content
update	Update comment	commentId, content
delete	Delete comment	commentId
delete_thread	Delete thread	threadId
resolve	Resolve thread	threadId
reopen	Reopen thread	threadId
unread	Unread count	fileId

penpot_team

Action	Description	Required Params
list	List teams	-
get	Get team	teamId
create	Create team	name
rename	Rename team	teamId, name
delete	Delete team	teamId
members	List members	teamId
invite	Invite member	teamId, email, role
remove_member	Remove member	teamId, memberId
update_role	Update role	teamId, memberId, role
invitations	Pending invites	teamId
cancel_invite	Cancel invite	invitationId
leave	Leave team	teamId
stats	Team statistics	teamId

penpot_profile

Action	Description	Required Params
get	Get profile	-
update	Update profile	-
password	Change password	oldPassword, newPassword
props	Get properties	-
update_props	Update props	props
email	Request email change	newEmail
delete	Delete account	-
recent	Recent files	-
notifications	Notifications	-
mark_read	Mark as read	notificationId

penpot_library

Action	Description	Required Params
shared	List shared	teamId
link	Link library	fileId, libraryId
unlink	Unlink library	fileId, libraryId
linked	List linked	fileId
publish	Publish library	fileId
unpublish	Unpublish	fileId
summary	Library summary	fileId
sync	Sync library	fileId, libraryId
colors	Library colors	libraryId
typography	Library typography	libraryId
components	Library components	libraryId
search	Search libraries	teamId, query

penpot_search

Action	Description	Required Params
files	Search files	query
objects	Search objects	fileId, query
components	Search components	fileId
colors	Search colors	fileId
typography	Search typography	fileId
recent	Recent files	-
global	Global search	query

penpot_analyze

Action	Description	Required Params
design_system	Design system audit	fileId
accessibility	Accessibility check	fileId
naming	Naming conventions	fileId
structure	File structure	fileId
colors	Color analysis	fileId
typography	Typography analysis	fileId
components	Component usage	fileId
duplicates	Find duplicates	fileId

Example Usage

List all projects

{
  "tool": "penpot_projects",
  "arguments": {
    "action": "list"
  }
}

Search for files

{
  "tool": "penpot_search",
  "arguments": {
    "action": "files",
    "query": "dashboard"
  }
}

Export component as PNG

{
  "tool": "penpot_exports",
  "arguments": {
    "action": "export",
    "fileId": "file-uuid",
    "objectId": "object-uuid",
    "format": "png",
    "scale": 2
  }
}

Get design tokens as CSS

{
  "tool": "penpot_tokens",
  "arguments": {
    "action": "export_css",
    "fileId": "file-uuid"
  }
}

Analyze design system

{
  "tool": "penpot_analyze",
  "arguments": {
    "action": "design_system",
    "fileId": "file-uuid"
  }
}

Development

# Development mode with hot reload
npm run dev

# Build
npm run build

# Run tests
npm test

API Reference

This MCP server uses Penpot's RPC API with Transit+JSON encoding:

• UUIDs are encoded with ~u prefix
• Keywords are encoded with ~: prefix
• All requests go through /rpc/command/{command-name}

License

MIT