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
[email protected]
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": "[email protected]",
        "PENPOT_PASSWORD": "your-password"
      }
    }
  }
}

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

{
  "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