Inspect Penpot Files And Live Surfaces

Use this when you need to understand a Penpot file or local Penpot workspace in a way that can later become deterministic tooling.

Important format note:

current exported .penpot files should be treated as ZIP archives with readable JSON structure and assets
older binary .penpot format references exist historically, but Penpot documents that older binary format as deprecated
verify the actual artifact in front of you instead of assuming the older format

Inspect The File Artifact

Confirm the file type:

file /path/to/file.penpot

List archive contents:

unzip -l /path/to/file.penpot

If unzip -l shows structured archive contents, continue with file/page/shape inspection rather than treating the file as opaque.

Read top-level file metadata:

unzip -p /path/to/file.penpot files/<file-id>.json

Read page metadata:

unzip -p /path/to/file.penpot files/<file-id>/pages/<page-id>.json

Read the root object for a page:

unzip -p /path/to/file.penpot \
  files/<file-id>/pages/<page-id>/00000000-0000-0000-0000-000000000000.json

Read a specific shape or component object:

unzip -p /path/to/file.penpot \
  files/<file-id>/pages/<page-id>/<shape-id>.json

If the local Penpot stack is running, inspect the backend docs:

curl -L http://localhost:9001/api/main/doc | head

Browser URL:

If the local Penpot MCP runner is active:

Check the plugin manifest:

curl http://localhost:4400/manifest.json

Check the MCP endpoint:

curl -i http://localhost:4401/mcp

Expected behavior:

the manifest should return JSON
the MCP endpoint may return 405 Method Not Allowed on a simple GET or HEAD, which still proves the HTTP server is listening

Prefer this order:

The purpose is to keep Penpot work: