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

Related MCP server: pixelforge-mcp

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.