mcp-pixel-img

MCP server for pixel-img — expose the pixel-img API as MCP tools over HTTP/SSE for remote hosting (Coolify, Railway, Fly.io, etc.).

What is this?

pixel-img is a Next.js API that generates images (PNG/JPEG/WEBP) from HTML/CSS templates using Puppeteer. This MCP server wraps that API so Claude can use it directly as tools — generate social media visuals, bulk-process Airtable records, manage templates and galleries, and more.

Unlike the built-in stdio MCP (bundled inside pixel-img), this server uses SSE transport so it can be hosted remotely and shared across multiple Claude instances.

Tools exposed

Tool	Description
list_templates	List templates with optional search/category/favorite filters
get_template	Get a template by ID
create_template	Create a new template (supports $meta.columnName placeholders)
update_template	Update an existing template
generate_image	Generate an image from raw HTML/CSS
generate_from_template	Generate from a saved template, with optional Airtable write-back
bulk_generate	Generate one image per datasource record, save to gallery
list_datasources	List configured datasources (Airtable, Baserow, Supabase)
fetch_records	Fetch all records from a datasource
get_record	Get a specific record by index or field value
list_galleries	List image galleries
create_gallery	Create a new gallery
list_presets	List social media presets with dimensions
list_fonts	List available Google Fonts
health	Check pixel-img instance status

Deploy on Coolify

1. Add the repo to Coolify

• Source: https://github.com/Oliviercreativ/mcp-pixel-img
• Build pack: Dockerfile
• Port: 3001

2. Set environment variables

Variable	Required	Description
PIXEL_IMG_URL	Yes	Your pixel-img base URL (e.g. https://pixel-img.vercel.app)
PIXEL_IMG_API_KEY	Yes	Your API_PASSWORD from pixel-img
MCP_SECRET	Recommended	Bearer token to protect the SSE endpoint
PIXEL_IMG_WEBHOOK_SECRET	Optional	For Airtable write-back via webhook
PORT	Optional	Default: 3001

3. Deploy

Coolify will build the Docker image and start the server. The SSE endpoint will be available at:

https://your-coolify-domain/sse

Connect Claude to this server

Add this to your ~/.claude.json (Claude Code):

{
  "mcpServers": {
    "pixel-img": {
      "type": "sse",
      "url": "https://your-coolify-domain/sse",
      "headers": {
        "Authorization": "Bearer YOUR_MCP_SECRET"
      }
    }
  }
}

If MCP_SECRET is not set, omit the headers block.

Quick start with npx

PIXEL_IMG_URL=https://pixel-img.vercel.app \
PIXEL_IMG_API_KEY=your_api_password \
MCP_SECRET=your_secret \
npx mcp-pixel-img

Run locally (from source)

# Clone and install
git clone https://github.com/Oliviercreativ/mcp-pixel-img
cd mcp-pixel-img
npm install

# Configure
cp .env.example .env
# Edit .env with your values

# Development (hot reload)
npm run dev

# Production build
npm run build
npm start

The server listens on http://localhost:3001 by default.

Endpoints

Endpoint	Description
GET /sse	SSE stream — Claude connects here
POST /messages?sessionId=xxx	MCP message relay
GET /health	Health check (no auth required)

Architecture

Claude Code / Claude.ai
        │  SSE connection
        ▼
  mcp-pixel-img  (this server, hosted on Coolify)
        │  REST API calls (Bearer token)
        ▼
  pixel-img API  (hosted on Vercel)
        │
        ▼
  Neon Postgres + Puppeteer/Chromium

License

MIT