pmcp — PlaceholderMCP CLI

Placeholder image generation from the command line, for developers and coding agents. Wraps the PlaceholderMCP API (api.placeholdermcp.com). Zero dependencies.

Works with: Claude Code · Cursor · Cline · Windsurf · Aider · Codex · any MCP client

Login to first image in 60 seconds — watch the full demo.

Install

npm install -g placeholdermcp

Quickstart

pmcp start                       # instant: mint a key — no account, no card (48h window)
pmcp gen 400x300 --bg 6366f1 --text "Hello" -o hero.png

One command, zero signup. After the 48-hour card-free window, requests return 402 until you add a card ($1/mo Basic) — your key stays valid.

With an account:

pmcp init                        # setup guide + agent instructions
pmcp login [email protected]         # JWT for account ops
pmcp keys create my-key --save   # API key for image requests (saved to .pmcp/config.json)

Auth model

| Credential | Header | Used for | |---|---|---| | JWT (from pmcp login) | Authorization: Bearer <jwt> | me, keys, usage, billing | | API key (key_...) | X-API-Key | image generation, MCP tools |

Config priority: flags (--key/--token/--url) → env (PMCP_API_KEY/PMCP_TOKEN/PMCP_URL) → .pmcp/config.json (project-local).

MCP server

Built for agents — machine-readable schema, profile and plan straight from the terminal.

Save as .mcp.json in your project root:

{
  "mcpServers": {
    "placeholdermcp": {
      "type": "stdio",
      "command": "pmcp",
      "args": ["mcp-serve"]
    }
  }
}

Tools: get_image_url, generate_placeholder, get_usage, list_plans.

Agent schema

pmcp init --agent-schema prints a machine-readable JSON contract of all commands and flags — load it into agent context to prevent flag hallucination.

Commands

Run pmcp --help for the full reference.