tokven-mcp

WCAG-safe color system generation for AI agents and developers. Give it a brand hex, get a contrast-validated token system in CSS, Tailwind, or DTCG JSON. Runs locally, no account needed.

What it does

Give it a brand color and a mood. It returns a full token system: colors (light + dark mode), typography pairing, spacing scale, border radius, shadows — all WCAG-validated with contrast ratios. Output as CSS custom properties, Tailwind v4, Tailwind v3, or DTCG JSON. Runs locally, no account needed.

Install

{
  "mcpServers": {
    "tokven": {
      "command": "npx",
      "args": ["-y", "tokven-mcp"]
    }
  }
}

Cursor: Settings → MCP → Add the config above

Claude Desktop: Add to claude_desktop_config.json

Claude Code:

claude mcp add tokven -- npx -y tokven-mcp

Using as a project dependency

If tokven-mcp is installed locally (e.g. in node_modules), agents can invoke it directly via stdio without npx:

{
  "mcpServers": {
    "tokven": {
      "command": "node",
      "args": ["node_modules/tokven-mcp/bin.js"]
    }
  }
}

Recommended workflow

For the best results — especially when an agent is applying tokens on behalf of a user — follow this three-step flow:

1. Preview first. Call get_token_preview with the brand hex and mood. It returns key colors, fonts, contrast summary, and a visual preview URL on tokven.dev.
2. Share the preview URL. Surface the url field to the user (e.g. https://tokven.dev/?hex=2563eb&mood=corporate) so they can see the palette visually before committing.
3. Generate tokens. Once the user approves the palette, call generate_tokens with the same parameters for full CSS/Tailwind/DTCG output.

This avoids the common pitfall of applying a palette the user has never visually confirmed.

Tools

generate_tokens

Generates a complete token system from a hex color.

| Parameter | Required | Description | |-----------|----------|-------------| | hex | yes | Brand color, e.g. #2563eb | | mood | no | Visual personality. Default: cool | | format | no | css | tailwind-v4 | tailwind-v3 | dtcg | | heading_font | no | Override heading font family | | body_font | no | Override body font family | | colors | no | Color scope: primary | primary-secondary | all (default) | | secondary_hex | no | Custom secondary hex. Auto-derived if omitted | | tertiary_hex | no | Custom tertiary hex. Auto-derived if omitted |

Example prompt:

Generate a design system for #2563eb with a corporate mood as Tailwind v4

Returns: Full CSS/Tailwind/DTCG output, Google Fonts @import URL, WCAG contrast results for both light and dark mode, and a url linking to a visual preview on tokven.dev.

get_token_preview

Quick summary without full CSS. Recommended first step — call this before generate_tokens so the user can approve the palette visually.

| Parameter | Required | Description | |-----------|----------|-------------| | hex | yes | Brand color | | mood | no | Mood preset |

Example prompt:

Preview tokens for #e05aad with a soft mood

Returns: Primary colors, font pairing, radius, shadow style, contrast pass/fail count, and a url linking to a visual preview on tokven.dev. Share this URL with the user for visual confirmation before generating full tokens.

validate_contrast

WCAG 2.1 contrast check between two colors.

| Parameter | Required | Description | |-----------|----------|-------------| | foreground | yes | Foreground hex color | | background | yes | Background hex color |

Example prompt:

Does #ffffff on #2563eb pass WCAG AA?

Returns: Contrast ratio, AA/AAA pass/fail for normal and large text.

list_moods

Returns all 14 mood presets with descriptions. No parameters.

| Mood | Character | |------|-----------| | warm | Earthy tones, serif typography, editorial | | cool | Blue-grey, clean sans-serif, professional | | bold | High contrast, saturated, hard shadows | | dark | Muted, precise, monospace-friendly | | soft | Pastel, rounded shapes, gentle | | minimal | Near-achromatic, elegant, restrained | | brutalist | Monochrome, raw, zero radius | | playful | High chroma, bouncy, colorful | | vintage | Desaturated warm, classic serif | | luxury | Gold/champagne, refined serif | | nature | Green/earth tones, organic shapes | | neon | Dark bg, max chroma, cyber | | corporate | Professional blue, trustworthy | | retro | Warm saturated, 70s/80s display |

Response structure

generate_tokens

{
  "css": "/* full token output — CSS custom properties, Tailwind, or DTCG */",
  "fonts": {
    "heading": "Raleway",
    "body": "Noto Sans",
    "importUrl": "https://fonts.googleapis.com/css2?family=Raleway:wght@600&family=Noto+Sans:wght@400&display=swap"
  },
  "contrast": { "light": "31/31 pass", "dark": "31/31 pass" },
  "mood": "corporate",
  "format": "css",
  "url": "https://tokven.dev/?hex=2563eb&mood=corporate"
}

get_token_preview

{
  "mood": "corporate",
  "colors": {
    "primary": "#2563eb",
    "background": "#f6f7fa",
    "surface": "#f0f2f6",
    "text": "#0e1016"
  },
  "fonts": { "heading": "Raleway", "body": "Noto Sans" },
  "radius": "6px",
  "shadow": "medium",
  "contrast": { "light": "31/31 pass", "dark": "31/31 pass" },
  "url": "https://tokven.dev/?hex=2563eb&mood=corporate"
}

Example output

generate_tokens with hex: "#2563eb", mood: "corporate" returns:

@import url("https://fonts.googleapis.com/css2?family=Raleway:wght@600&family=Noto+Sans:wght@400&display=swap");

:root {
  /* Background */
  --color-bg: #f6f7fa;
  --color-bg-surface: #f0f2f6;
  --color-bg-elevated: #eaecf1;
  --color-border-subtle: #e2e4ea;
  --color-border-default: #d8dbe2;
  --color-border-strong: #c7cad2;

  /* Text */
  --color-text: #0e1016;
  --color-text-muted: #454856;
  --color-text-subtle: #6a6e7b;

  /* Primary */
  --color-primary: #2563eb;
  --color-primary-on: #ffffff;
  --color-primary-container: #e8edf8;
  /* ... 45 more color tokens, typography, spacing, radius, shadows */
}

Plus WCAG contrast validation:

{ "light": "31/31 pass", "dark": "31/31 pass" }

Examples

Example 1: Generate tokens for a brand color

User prompt: "Generate a design system for my app using brand color #2563eb"

Expected behavior:

• Calls generate_tokens with hex #2563eb, mood "cool"
• Returns full CSS custom properties block
• Includes Google Fonts @import URL
• Shows WCAG contrast results: 31/31 pass for both light and dark mode

Example 2: Preview and compare moods

User prompt: "Show me a preview of #e05aad with a soft mood before I commit"

Expected behavior:

• Calls get_token_preview
• Returns compact summary: primary colors, font pairing, radius, shadow style, contrast pass count
• Includes a url to tokven.dev for visual preview — share with the user before committing to full generation
• No full CSS — quick comparison view

Example 3: Check if colors are accessible

User prompt: "Does white text on #2563eb pass WCAG AA?"

Expected behavior:

• Calls validate_contrast with #ffffff and #2563eb
• Returns ratio (4.52:1), AA pass for large text, AA fail for normal text, AAA fail
• Clear pass/fail for each WCAG criterion

Privacy

tokven-mcp runs entirely on your local machine. No data is collected, no network requests are made during token generation, no account required. The MCP server collects no usage data.

Full policy: https://tokven.dev/#/privacy

Requirements

Node.js >= 18

License

MIT