E

Usage & 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/colors

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

curl https://espectro.dev/api/colors?search=pink
GET /api/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/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/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/combinations/random

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

curl https://espectro.dev/api/combinations/random

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

search-colors Search colors by name or hex value
get-color Get full details for a specific color
search-combinations Filter combinations by palette size or color name
get-combination Get a combination with all color data
random-combination Get a random palette for inspiration
export-combination Generate Tailwind or CSS export for a combination

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]
      },
      ...
    ]
  }
}