tokven-mcp

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:

• 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.
• 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.
• 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