penpot

This Penpot MCP server exposes a set of 68 tools that allow an AI agent to read, create, modify, and export Penpot design elements through the MCP protocol. The server runs as a network service (HTTP) and connects to your self-hosted Penpot instance, providing programmatic access to projects, shapes, text, exports, and more. Clients connect to the MCP endpoint over HTTP at the configured port (default 8787) and can initialize an MCP session, discover available tools, and issue RPC-style commands to manipulate Penpot data. The system is designed to route reads directly to PostgreSQL for speed, route writes through Penpot's RPC API to keep history and undo tracking intact, and use Penpot's exporter for pixel-perfect SVG/PNG exports. To use with your AI agent ( Claude Code, Gemini CLI, or others ), point the agent at http://<host>:8787/mcp and enumerate the available tools to perform design tasks via natural language instructions. For client configuration, you typically declare the penpot server under the mcpServers map with the appropriate transport (http) and URL, then authorize or supply credentials via the server’s own environment (not the client).

Prerequisites:

• Docker and Docker Compose installed on the host
• Git installed
• Access tokens enabled in your Penpot instance

Option A: Automated Setup

1. Clone the repository (or use the image directly if you prefer):

git clone https://github.com/ancrz/penpot-mcp-server.git
cd penpot-mcp-server

2. Build and run using the included Docker setup (as described in the README):

# If you have a setup script in the repo, use it
chmod +x setup.sh
./setup.sh

3. Ensure the MCP service is reachable at http://<host>:8787/mcp and prepare your Penpot credentials in the server’s environment.

Option B: Manual Docker Run

1. Prepare an environment file or inline env vars with your Penpot credentials:

PENPOT_ACCESS_TOKEN=your-token-here
PENPOT_DB_PASS=your-db-password
PENPOT_PUBLIC_URL=http://localhost:9001

2. Run the MCP server container:

docker run -d --name penpot-mcp \
  -e PENPOT_ACCESS_TOKEN="$PENPOT_ACCESS_TOKEN" \
  -e PENPOT_DB_PASS="$PENPOT_DB_PASS" \
  -e PENPOT_PUBLIC_URL="$PENPOT_PUBLIC_URL" \
  -p 8787:8787 \
  -p 9001:9001 \
  ancrz/penpot-mcp-server

3. Verify basic health:

curl -s http://localhost:8787/

4. Initialize the MCP protocol (example):

curl -s http://localhost:8787/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

If you prefer an all-in-one script, use the project’s setup.sh to automate configuration, image build, and startup.

Notes and tips:

• The MCP server communicates over HTTP (streamable HTTP) and uses port 8787 for MCP API and 9001 for Penpot frontend in the described setup. Adjust ports as needed in your docker setup.
• The server’s credentials (PENPOT_ACCESS_TOKEN, PENPOT_DB_PASS, etc.) live in the server environment, not in the client MCP config. The client’s env block is ignored for network servers.
• For Claude Code, use the http transport mapping: set up your ~/.claude.json or project-level .mcp.json to point to http://localhost:8787/mcp and expect 68 tools when querying the penpot MCP server.
• If you run Penpot in Docker, consider adding a dedicated Penpot container and a dedicated MCP container in the same Docker network for reliable hostname-based access.
• Common issues include incorrect tokens, database password mismatches, or port conflicts. Check container logs for details when the MCP endpoint returns errors.
• You can monitor the container logs with: docker logs -f penpot-mcp
• Ensure Docker Compose setups for Penpot are configured to expose the same network so the MCP server can reach Penpot if running separately.