Usage and API

espectro.dev provides a free, open JSON API for accessing Sanzo Wada's 159 colors and 348 color combinations. No authentication required.

Rate Limiting

The REST API is limited to 15 requests per minute per IP address. Standard X-RateLimit-* headers are included in every response.

The MCP endpoint uses a separate, higher limit (120/min by default). When MCP clients send a session identifier (e.g. X-MCP-Session-Id), requests are keyed per session instead of per IP, so shared infrastructure (e.g. one IP for all Claude users) does not share one small bucket.

Base URL

https://espectro.dev/api

Colors

GET /api/sanzo-wada/colors

List all 159 colors. Optionally filter by name or hex with ?search=pink.

curl https://espectro.dev/api/colors?search=pink
GET /api/sanzo-wada/colors/{slug}

Get a single color by slug. Returns hex, RGB, CMYK, L*a*b*, and combination IDs.

curl https://espectro.dev/api/colors/hermosa-pink

Combinations

GET /api/sanzo-wada/combinations

List all 348 combinations. Filter by palette size with ?size=2 (2, 3, or 4).

curl https://espectro.dev/api/combinations?size=3
GET /api/sanzo-wada/combinations/{id}

Get a single combination by ID (1–348). Returns full color data for each color in the palette.

curl https://espectro.dev/api/combinations/42
GET /api/sanzo-wada/combinations/random

Get a random combination. Great for inspiration or placeholder palettes.

curl https://espectro.dev/api/combinations/random
GET /api/werner/colors

All 110 colors from Werner's Nomenclature of Colours (1814), with family and the book's animal, vegetable and mineral examples. Search with ?search= by name, hex, family or example.

curl https://espectro.dev/api/werner/colors?search=moss
GET /api/werner/colors/{slug}

One Werner color by slug.

curl https://espectro.dev/api/werner/colors/scotch-blue
GET /api/ridgway/colors

All 1,115 colors from Ridgway's Color Standards and Color Nomenclature (1912), with plate, hue, tone and hue group. Search with ?search= by name, hex, plate or hue group.

curl https://espectro.dev/api/ridgway/colors?search=olive
GET /api/ridgway/colors/{slug}

One Ridgway color by slug.

curl https://espectro.dev/api/ridgway/colors/indulin-blue

MCP Integration

espectro.dev exposes its color data as MCP (Model Context Protocol) tools, so AI assistants (Cursor, Claude, etc.) can query colors and combinations directly. Use either the Laravel package in your own app (if Laravel) or the remote URL below.

Laravel package (connector)

For Laravel projects, install the official connector package. It creates a .mcp.json so Cursor auto-detects Espectro — no local MCP server required.

1. Install the package:

composer require labrodev/laravel-mcp-espectro

2. Run the install command:

php artisan espectro:install

This creates .mcp.json in your project root and prints the MCP endpoint URL. Restart Cursor and it will connect to https://espectro.dev/mcp/espectro automatically.

Use remotely (no install)

Anyone can connect to the public MCP endpoint from their AI assistant without installing anything.

MCP server URL:

https://espectro.dev/mcp/espectro

In your MCP client, add a new server that uses the HTTP (or SSE) transport and the URL above. MCP uses a separate, higher rate limit (see Rate Limiting above) and can key by session when clients send session headers.

Example: Add in Claude

In Claude (claude.ai or the desktop app), add Espectro as a custom connector:

  1. Open Add custom connector (or your client’s equivalent).
  2. Name: e.g. Espectro.
  3. Remote MCP server URL: https://espectro.dev/mcp/espectro
  4. Save and add the connector. Claude can then use the Espectro tools to search colors and combinations.

Only use connectors from developers you trust. This endpoint is provided by espectro.dev and is subject to MCP rate limits (see above).

Available tools

sanzo-wada-search-colors Search colors by name or hex value
sanzo-wada-get-color Get full details for a specific color
sanzo-wada-search-combinations Filter combinations by palette size or color name
sanzo-wada-get-combination Get a combination with all color data
sanzo-wada-random-combination Get a random palette for inspiration
sanzo-wada-export-combination Generate Tailwind or CSS export for a combination
werner-search-colors Search Werner's 110 colors by name, hex, family or natural example
werner-get-color Get a Werner color with its examples and the closest Sanzo Wada colors
ridgway-search-colors Search Ridgway's 1,115 colors by name, hex, plate or hue group
ridgway-get-color Get a Ridgway color with the same-name and closest Sanzo Wada colors

Example Response

{
  "data": {
    "id": 42,
    "size": 3,
    "colors": [
      {
        "id": 42,
        "name": "Ivory Buff",
        "slug": "ivory-buff",
        "hex": "#ebd999",
        "rgb": [235, 217, 153],
        "cmyk": [8, 15, 40, 0]
      },
      ...
    ]
  }
}