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

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
.husky		.husky
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
CAPABILITIES.md		CAPABILITIES.md
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
ISSUES.md		ISSUES.md
LICENSE		LICENSE
README.md		README.md
create-complete-design.cjs		create-complete-design.cjs
design-mobile-app.cjs		design-mobile-app.cjs
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
test-all-tools.cjs		test-all-tools.cjs
test-text.cjs		test-text.cjs
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Penpot MCP Server

Features

Architecture

Installation

Configuration

Usage with Claude Desktop

Available Tools (14 Total)

Core Tools

Legacy Tools (Backward Compatibility)

Tool Actions Reference

penpot_projects

penpot_files

penpot_components

penpot_tokens

penpot_exports

penpot_comments

penpot_team

penpot_profile

penpot_library

penpot_search

penpot_analyze

Example Usage

List all projects

Search for files

Export component as PNG

Get design tokens as CSS

Analyze design system

Development

API Reference

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

Packages