grayscale-mcp

An MCP server for grayscale.design. Agents can build luminance-based color palettes from base colors and export them the same way the site does.

The math is the site's own code. src/site/color.js is an unedited copy of the site's resources/js/utils/color.js, and the palette, naming, lock, share-link and export logic is ported line for line from App.vue, PaletteRow.vue and ExportController.php. Every palette and export was checked against the live site (see Verification).

The server is read-only. It needs no account and no secrets, stores nothing, and never calls grayscale.design.

Remote endpoint: https://mcp.grayscale.design/mcp (Streamable HTTP, stateless, no auth, 120 requests a minute per IP). https://grayscale-mcp.fly.dev/mcp serves the same app. Use of the hosted endpoint is covered by Hosted service.

Install

Claude Code

# remote (nothing to install)
claude mcp add --transport http grayscale-design https://mcp.grayscale.design/mcp

# or local stdio
git clone https://github.com/truefrontier/grayscale-mcp && cd grayscale-mcp && npm install && npm run build
claude mcp add grayscale-design -- node "$PWD/dist/stdio.js"

Cursor / Grok Bot

Add this to ~/.cursor/mcp.json (or a project's .cursor/mcp.json):

{
  "mcpServers": {
    "grayscale-design": { "url": "https://mcp.grayscale.design/mcp" }
  }
}

For local stdio, use { "command": "node", "args": ["/absolute/path/to/grayscale-mcp/dist/stdio.js"] }.

Grok Bot uses the same thing. Add a custom MCP connector with the URL https://mcp.grayscale.design/mcp and no auth.

Any other MCP client

• Streamable HTTP: POST https://mcp.grayscale.design/mcp. No auth; send Accept: application/json, text/event-stream.

• stdio: node dist/stdio.js.

• Clients that only support stdio: npx -y mcp-remote https://mcp.grayscale.design/mcp.

Related MCP server: MCP Color Converter

Tools

Not covered

• Image upload → palette. The site posts the image to its own server (CSRF-protected) and reads the colors back from imgix. An MCP would be writing files to that server, so this tool leaves it out. Pass the colors directly instead.

• Saved palettes / accounts. The site has neither. Its only users are Statamic admins, and the share URL is how a palette gets saved, so generate_palette returns that URL and accepts it back as input.

• Demo videos and the feedback link.

Site quirks kept on purpose

These are replicated so the output matches the site exactly:

• With Radix + OKLCH, the export stops after the header (the site throws inside a try/catch).

• Stylus shade labels are 100, 200, 300… whatever the count (the site passes a boolean as the count).

• When a share link has an unnamed palette before a named one, the site moves the name onto the wrong palette on load. generate_palette({ share_url }) does the same.

Hosted service

The endpoint at https://mcp.grayscale.design/mcp (and https://grayscale-mcp.fly.dev/mcp) is provided free and as-is, with no guarantee of uptime or accuracy. It may change, be rate-limited, or shut down at any time without notice.

Acceptable use. Don't abuse or overload the service, don't try to get around the rate limit, and don't use it for anything illegal. We may block traffic that does.

Data. The server doesn't need an account, stores nothing you send, and doesn't write request or IP logs. To enforce the rate limit it keeps each client IP address in memory for about a minute, then drops it. The service is hosted on Fly.io, which routes the traffic and handles it under its own privacy policy. We don't sell any data.

License

MIT, Copyright (c) 2026 Brandname Maker LLC d/b/a True Frontier. Credits for the color formulas are in THIRD_PARTY.md.

The grayscale.design and True Frontier names and logos aren't covered by this license.

Develop

npm install
npm run build
npm test                                    # stdio: calls every tool through an MCP client
node scripts/smoke.mjs http://localhost:8080/mcp   # HTTP, after `npm run start:http`
fly deploy                                  # remote (app: grayscale-mcp)

Verification

Seven palettes (one color, three colors, presets, hue/sat tweaks, lock, 7 custom shades) were loaded in headless Chrome from the live grayscale.design share links. The site's own export computeds were compared with this server's output: 8 export tabs × 4 color types, plus /export-svgs.

• In the six cases compared swatch by swatch, all 163 swatches matched exactly in hex, rgb and hsl.

• 222 of 224 export texts matched byte for byte. The two that differ are only the share link in the header comment: the site's first render still has the URL from before its name-shift quirk ran.

• All 7 SVG files matched.

• Presets, the 15-shade resize, suggested colors and /false-color also matched.