Setting up Penpot MCP for Codex

This page describes how to connect Codex to Penpot using the hosted Penpot MCP server.

Codex connects to the hosted Penpot MCP endpoint provided by Penpot. The currently open Penpot file must also be connected from the browser side.

Codex -> hosted Penpot MCP server -> Penpot browser connection -> current Penpot file

In Penpot:

• Go to Account → Integrations
• Enable MCP Server
• Generate/copy the MCP credentials

Penpot provides the credentials as JSON, for example:

{
  "mcpServers": {
    "penpot": {
      "url": "https://design.penpot.app/mcp/stream?userToken=YOUR_PENPOT_MCP_TOKEN"
    }
  }
}

In your project directory, save the JSON as:

.mcp.json

Do not commit this file. The userToken is a secret.

Codex requires Node.js/npm.

npm install -g @openai/codex
codex login

From the same project directory, run:

codex mcp add penpot --url "$(jq -r '.mcpServers.penpot.url' .mcp.json)"

This reads the hosted Penpot MCP URL from .mcp.json and adds it to Codex as an MCP server named penpot.

Open the relevant Penpot design file in the browser. Then connect the file to MCP from the Penpot UI:

• Open the design file
• Choose … (three dots menu) → MCP Server → Connect
• Keep the Penpot browser tab open while Codex is using the design

Start Codex in the project directory:

codex

Inside Codex, run:

/mcp

The penpot MCP server should appear in the list. You can also ask Codex to inspect the connected design, for example:

List all pages in the connected Penpot file.