penpot-api-mcp

[

MCP server wrapping the Penpot REST API for headless design automation. Provides read, search, and export access to Penpot projects, files, and design objects — without requiring a browser session.

Why this exists

The official @penpot/mcp (TypeScript) requires a live browser plugin to operate — it is the right tool for interactive canvas manipulation. This server targets the complementary use case: background automation, asset export pipelines, and AI-driven design queries that run without a browser.

Tools

Setup

uv sync
touch .env             # then fill in credentials (see Configuration below)

Configuration

Environment variables (prefix PENPOT_):

Either PENPOT_ACCESS_TOKEN or PENPOT_EMAIL + PENPOT_PASSWORD must be set.

Transport settings (prefix PENPOT_MCP_)

The CLI transport layer uses a separate env prefix from the Penpot API client. Override defaults via:

Note: PENPOT_HTTP_PORT (without the MCP_ segment) is not honored by the CLI; the active prefix is PENPOT_MCP_.

Running

# HTTP mode (default — Claude Code compatible)
uv run python -m penpot_api_mcp start --force

Server listens on http://localhost:3051/mcp. The server is HTTP-only; bare uv run python -m penpot_api_mcp without a subcommand falls through to Typer help and does not start a JSON-RPC loop. To bridge to stdio, run the HTTP server behind an external stdio-to-HTTP shim.

MCP configuration

{
  "mcpServers": {
    "penpot-api": {
      "type": "http",
      "url": "http://localhost:3051/mcp"
    }
  }
}

Installation via Claude Code marketplace

This repo ships a Claude Code plugin manifest (.claude-plugin/plugin.json) plus a colocated .mcp.json and three slash commands in commands/. To install, register the www-mcp-servers marketplace with Claude Code, then install the plugin by name. Once installed, the slash commands /penpot-list, /penpot-search, and /penpot-export become available alongside the mcp__penpot-api__* tools, and the MCP client talks to the server over http://localhost:3051/mcp as configured in .mcp.json. Penpot credentials still need to be present in the environment (PENPOT_ACCESS_TOKEN or PENPOT_EMAIL + PENPOT_PASSWORD); the plugin manifest only wires the transport, it does not provision Penpot auth.

Development

uv run pytest                          # Run tests
uv run crackerjack                     # Full quality suite (ruff + mypy + pytest + bandit)
uv run ruff check --fix                # Lint
uv run mypy .                          # Type check

Architecture

penpot_api_mcp/
├── utils/transit.py      # Transit+JSON encode/decode (Penpot's wire format)
├── config/settings.py    # Pydantic settings (PENPOT_* env vars)
├── clients/              # httpx async client with dual auth
├── models/               # Pydantic models: Project, File, Object, ObjectTree
├── tools/                # FastMCP tool registrations
├── server.py             # FastMCP app + health endpoints
└── __main__.py           # MCPServerCLIFactory entrypoint (Oneiric)

Transit+JSON

Penpot's RPC layer uses Transit+JSON — a Clojure serialization format where map keys are ~:keyword and UUIDs are ~uUUID. The utils/transit.py module handles encode/decode at the API boundary, keeping all Python models clean.

Authentication

Two modes are supported:

• API token (PENPOT_ACCESS_TOKEN): sent as Authorization: Token <token> header
• Email + password: authenticates via /rpc/command/login-with-password, then relies on the httpx cookie jar (auth-token cookie) for all subsequent requests

License

BSD 3-Clause. See LICENSE.

Built on Oneiric for runtime configuration and mcp-common for the FastMCP baseline. Crackerjack gates every commit.