PerlerBeadAI MCP Server

Model Context Protocol server for fuse bead pattern tools — let AI clients (Claude Code, Cursor, Claude Desktop, Codex, etc.) convert images into bead patterns, generate AI pattern art, look up bead colors, match colors across brands, and estimate bead costs.

Server URL: https://perlerbeadai.com/wp-json/pba/v1/mcp
Transport:  Streamable HTTP (JSON-RPC 2.0)
Auth:       Bearer token (free account required)

Tools

Tool	Description	Rate Limit
pba_convert	Convert an image (URL or base64) into a bead pattern — color-quantized grid, per-color bead counts, rendered chart PNG. Supports 4 brands (Perler, Hama, Artkal-S, Artkal-C), boards 2–120 beads.	30/min per key
pba_generate	Generate bead-pattern-style art from a text prompt (gpt-image-2, ~1–4 min). Two-step: submit with prompt → poll with job_id every ~15s. Result opens directly in the AI editor. Uses your account quota (3 free/day + credits).	1/15s per key
pba_color_chart	Full color chart for a brand — Perler (103), Hama (92), Artkal-S (199), Artkal-C (174). Each entry: code, name, hex.	60/min per key
pba_convert_color	Find nearest bead colors across brands for a brand+code or any hex, using CIEDE2000 (ΔE grades: excellent <2, good <4, approximate <7, poor ≥7).	60/min per key
pba_estimate_cost	Turn per-color bead counts (e.g. from pba_convert) into bag counts and reference cost estimates.	60/min per key

Quick Start

1. Get an API key

Register a free account at perlerbeadai.com (5 bonus credits included), then open your account page → API Keys & MCP card and click Create key. Copy the key (pba_uk_…) — it's shown only once.

2. Add to your AI client

Claude Code:

claude mcp add --transport http perlerbeadai \
  https://perlerbeadai.com/wp-json/pba/v1/mcp \
  --header "Authorization: Bearer pba_uk_…"

Cursor / Claude Desktop:

{
  "mcpServers": {
    "perlerbeadai": {
      "url": "https://perlerbeadai.com/wp-json/pba/v1/mcp",
      "headers": {
        "Authorization": "Bearer pba_uk_…"
      }
    }
  }
}

Cursor: Settings → MCP → Add server. Claude Desktop: claude_desktop_config.json. Restart after saving.

Codex (OpenAI CLI):

[mcp_servers.perlerbeadai]
url = "https://perlerbeadai.com/wp-json/pba/v1/mcp"
http_headers = { "Authorization" = "Bearer pba_uk_…" }

Example Usage

Convert an image to a bead pattern

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pba_convert",
    "arguments": {
      "imageUrl": "https://example.com/photo.jpg",
      "width": 29,
      "brand": "perler",
      "maxColors": 25
    }
  }
}

Returns the bead grid (cells[y][x]), palette with hex/code/name/count, and a rendered chart PNG URL.

Generate AI pattern art

// Step 1 — submit
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pba_generate",
    "arguments": { "prompt": "a cute black cat with green eyes" }
  }
}
// → returns { "status": "pending", "job_id": "550e8400-…" }

// Step 2 — poll (repeat every ~15s until status=done)
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "pba_generate",
    "arguments": { "job_id": "550e8400-…" }
  }
}
// → returns { "status": "done", "imageUrl": "https://…", "editorUrl": "https://…" }

Match a hex color to nearest bead colors

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "pba_convert_color",
    "arguments": { "hex": "#FF6B8A", "targetBrand": "hama", "top": 3 }
  }
}

OAuth 2.1 PKCE

OAuth 2.1 with PKCE (S256) is also supported for client-side apps:

• Discovery: GET /.well-known/oauth-authorization-server/wp-json/pba/v1/mcp
• Authorize: /wp-json/pba/v1/oauth/authorize
• Token: /wp-json/pba/v1/oauth/token

Verify a key

curl -H "Authorization: Bearer YOUR_KEY" \
  https://perlerbeadai.com/wp-json/pba/v1/key/whoami

Server Implementation

The MCP server is implemented as a WordPress REST API handler. The reference implementation is in server/pbai-mcp.php.

Key features:

• JSON-RPC 2.0 over Streamable HTTP
• SSRF-safe image fetching (public-IP validation, DNS check, redirect limit, Content-Type verification)
• CIEDE2000 color distance math (full implementation ported from Python reference)
• GD-based chart rendering (bead-grid PNG generation)
• Rate limiting per API key with WordPress transients
• Audit logging (JSONL, key-hashed, per-month)
• OAuth 2.1 PKCE (S256, single-use codes, token cleanup)

Security

• API keys are SHA256-hashed at rest; raw keys are never stored
• SSRF protection: public-IP-only DNS validation, port 80/443 only, max 2 redirects, 10MB limit
• Image type verification via getimagesizefromstring() (PNG/JPEG/WebP/GIF only)
• IP-term filtering on AI prompts (copyrighted characters/brands rejected)
• Keys are revocable and regenerable instantly from the account page
• All calls are audit-logged (hashed key ID, timestamp, tool, latency)
• Uses hash_equals() for timing-safe key comparison

Pricing

• Free tier: 3 AI generations per day, unlimited for reference tools (convert, color chart, color matching, cost estimate)
• Credits: $0.50/generation beyond the free tier. Credits never expire — top up here
• Reference prices in pba_estimate_cost are planning estimates, not live shop prices

Links

• MCP Documentation
• Pattern Editor
• AI Generator
• Color Chart
• Free Patterns

License

MIT — see LICENSE.

---

Made with ❤️ by PerlerBeadAI — free fuse bead pattern maker & AI generator.