Enables agents to open Penpot workspace files and pages, inspect and modify designs through the Plugin API, export shapes as PNG/SVG, manage document sessions, and coordinate multi-agent access to Penpot projects.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
English | 繁體中文
Give your agent a Penpot link. The gateway handles the browser.
Penpot Better MCP wraps the official Penpot MCP with automatic file routing, managed headless browsers, and multi-agent scheduling. After setup and login, agents can open, read, edit, and export designs from workspace links. Users do not need to open a browser, connect the Penpot plugin, or keep a design tab active themselves.
The goal is a workflow closer to tools such as Figma: connect once, share a design link, and let agents work in the right file.
The official Penpot MCP workflow connects a plugin inside an open Penpot tab and follows its focused page. This gateway manages those editor sessions for you.
Task | Official plugin workflow | Penpot Better MCP |
Start working | Open a file in a browser and connect MCP | Pass a workspace URL; the gateway opens and connects a headless editor |
Switch files or pages | Manage the active tab and focused page | Each document handle identifies its file and page; calls activate the correct target automatically |
Run multiple agents | MCP uses the active tab's context | Different files run in parallel; calls to the same file, including different pages, run in sequence |
Work on a Linux VM | Arrange a running browser and plugin session | Run the supplied Docker setup without a desktop or |
Operations still use the official MCP and Plugin API under the logged-in user's Penpot permissions. See the upstream project for the underlying protocol and tools.
Related MCP server: Penpot MCP Server
The computer running this gateway automatically runs headless Chromium. It needs CPU and RAM for full Penpot editors. Large files, images, and more simultaneously open files increase that cost; the browser pool limits their number, not each editor's memory usage.
Allow several GiB of available RAM and CPU headroom. One measured four-client/PNG workload peaked at about 2.3 GiB for the gateway container; this is a workload-specific observation, not a minimum requirement or upper bound. The performance notes explain the measurements and limitations.
The default is two resident file browsers. For a smaller VM or mostly one large file, start with PENPOT_MAX_WORKERS=1. Raising it enables more parallel files but does not make calls within one file parallel. Idle browsers are reclaimed after ten minutes by default and reopened when needed.
Requires Docker Compose, Node.js 22+ for token initialization, and a Penpot account with access to the target files and permission to enable MCP. The login helper supports email/password login in your terminal.
Create or edit .env with your Penpot origin, using .env.example as a reference:
PENPOT_BASE_URL=https://penpot.example.comRun from the repository directory. Replace the login URL below with the same origin:
node scripts/init-state.mjs
docker compose build gateway
docker compose run --rm auth --base-url https://penpot.example.com --enable-mcp
docker compose up -d upstream gateway
curl http://127.0.0.1:4545/healthzRun login in your own interactive terminal; the password is hidden and is not saved. --enable-mcp enables MCP when needed without rotating an existing valid key. Login must finish before starting the gateway. If your host UID/GID differs from 1000:1000, set LOCAL_UID and LOCAL_GID in .env first.
The session and gateway token are stored locally in .state with mode 0600, excluded from Git and image builds, and mounted read-only by the gateway. If the session expires, repeat login and recreate the gateway. /healthz checks service liveness, not whether the Penpot session is still authorized.
Transport: Streamable HTTP
Endpoint: http://127.0.0.1:4545/mcp
Authorization header: Bearer <contents of .state/gateway-token>
Keep the token in the client's secret configuration: it grants access through the gateway's Penpot account. The supplied Compose setup binds to loopback; use an SSH tunnel for clients on another machine.
All agents must share the same HTTP endpoint to share scheduling. Agent A can edit file A while Agent B edits file B. If both target the same file, each tool call waits its turn, even when they target different pages. Separate gateway or stdio processes do not share locks.
A single client can also launch the gateway over stdio. Use the repository as its working directory:
docker compose up -d upstream
docker compose run --rm --no-deps -T gateway --stdioReconnect or refresh tool discovery after upgrades if your client retains an older tool list.
Edit these settings in .env. The supplied compose.yaml passes them to the relevant services:
Setting | Default | What it changes |
|
| Set your Penpot origin, without a file path. Use HTTPS except for loopback test sites; sign in to the same origin. |
|
| Resident file browsers, from |
|
| Idle time before browser reclamation; minimum |
|
| Set |
|
| Host HTTP port. Update the client endpoint when changing it. |
|
| Time Docker allows for accepted work and saves to finish before forcing a stop. Shortening it can interrupt work. |
|
| Container user IDs; match the owner of your local |
For example, set PENPOT_MAX_WORKERS=1 and PENPOT_IDLE_MS=300000 for one resident file and five-minute idle reclamation. After agents finish their current work, apply changes with:
docker compose up -d --force-recreate gatewayRestarting invalidates document handles; clients must reopen documents. Changing the site also requires a session for the new site. .env.example includes additional native Node settings; only variables referenced by compose.yaml affect this Docker setup. Native Node reads shell environment variables or an explicit node --env-file=.env dist/main.js; it does not load .env automatically.
To stop the service, use docker compose down. The gateway drains accepted operations and confirms saves before closing; failed shutdown saves are retried. Docker's grace period still bounds that wait.
Tool | Purpose |
| Open a workspace URL and return a |
| Inspect document information and recovery status |
| Return a handle for another page, keeping the old handle bound to its original page |
| Read or modify designs through the official Plugin API |
| Confirm pending batch changes are saved |
| Export PNG/SVG; |
| Confirm saves and release a handle; closing the last handle for a file releases its browser |
| Read official usage guidance and gateway instructions |
| Look up Plugin API types and members |
Open a document, read the relevant API guidance, inspect the design, then make focused edits. execute_code defaults to save="wait". For frequent reads or batched writes, save="deferred" avoids waiting for save confirmation on every call; finish writes with flush_document. A deferred reply confirms execution, not persistence.
For multi-agent work, put dependent read/compute/write steps in one execute_code call. Scheduling protects individual calls, not an entire agent workflow or a transaction. It does not lock human editors or other gateways. On EXECUTION_UNKNOWN or SAVE_UNCONFIRMED, open a fresh handle and read back before deciding what to do; do not blindly replay writes. See the agent guide.
One logged-in user and one Penpot site per gateway. Supported inputs are workspace URLs; viewer/share links and access to other sites are not supported.
A valid browser session is required. Automatic SSO/MFA login and multi-tenant isolation are not implemented; an existing authorized Playwright storageState can be supplied as .state/session.json.
Per gateway: up to 128 handles and 128 accepted operations, with 32 operations per file. A full operation queue returns BUSY; JavaScript is limited to 100,000 characters and HTTP request bodies to 1 MB.
The gateway forwards Plugin API operations within the deployed plugin's permissions. This does not mean every API method has been verified. Editing currently uses Chromium; direct backend API access is a future extension.
Faster, lower-cost bulk reads without relying on a browser.
Faster, lower-cost bulk writes.
npm ci
npm run check && npm test
npm run buildEach guide is available in English and Traditional Chinese:
Agent guide: pages, batching, collaboration, and recovery.
Architecture and diagnostics: routing, persistence, logs, and extension points.
Testing: isolated fixtures, real-instance acceptance, and coverage boundaries.
Performance: read/write overhead, concurrency, and resource measurements.
This project is licensed under the MIT License. Penpot and other dependencies retain their own licenses.
This server cannot be deployed
Agent-Native design tool - create and edit visual designs with agent assistance
A design agent in your coding agent's loop: briefs each screen, reviews UX and visual quality.
Give your AI agents a design superpower. Generate, edit, and publish publication-grade decks, reports, landing pages, resumes, and marketing visuals directly within your agent workflow. Delivering frontier-level design quality at 3× the speed and 53× lower cost -from conversational prompt to live link or vector PDF in minutes.
A real browser for your agent: screenshots, page checks, Markdown and PDFs.
