Skip to main content
Glama
design-tokens-mcp

design-tokens-mcp

by N-Link-Lab

design-tokens-mcp-server

デザイントークン(色・余白・フォント)を1つのJSONファイルで管理し、MCP経由でエージェントに読み書き・書き出し・ドリフト検知をさせる最小構成のMCPサーバーです。

FigmaのMCPサーバー+Skillエコシステムで注目される「デザイントークンをコードとデザインの間で同期し、ずれ(ドリフト)を検知する」というワークフローを、Figma契約なしで体験できる教材として実装しています。

できること

サーバーは5つのツールを公開します。

ツール

内容

tokens_list

トークン一覧(type / 名前プレフィックスで絞り込み可)

tokens_get

1件取得。名前が違うときは近い候補を提示

tokens_set

追加・更新。型ごとに値を検証(colorはhex、dimensionは単位付き数値など)

tokens_export

css / tailwind / figma-variables 形式で書き出し

tokens_check_drift

CSSファイル内のハードコードされた色・px値をトークンと照合し、ずれを最寄りトークン付きで報告

トークンファイルはW3C Design Tokens(DTCG)風の $type / $value 形式です。tokens.example.json を参照してください。

Related MCP server: eds-mcp-server

動作要件

  • Node.js 18以上(動作確認は v22)

セットアップ

git clone <このリポジトリのURL>
cd design-tokens-mcp
npm install
npm run build
npm test

npm test はビルド済みサーバーをstdioで起動し、5ツールすべて(バリデーションエラーとドリフト検知を含む16項目)を検証します。すべてPASSすれば準備完了です。

Claude Codeへの登録

claude mcp add design-tokens \
  --env TOKENS_FILE=/絶対パス/tokens.json \
  -- node /絶対パス/design-tokens-mcp/dist/index.js

TOKENS_FILE を省略するとカレントディレクトリの tokens.json を使います。初回は tokens.example.json をコピーして始めてください。

cp tokens.example.json tokens.json

他のMCPクライアント(Cursor等)でも、stdioサーバーとして node dist/index.js を登録すれば動きます。

使用例

エージェントへの指示例:

  • 「トークン一覧を見せて」→ tokens_list

  • 「spacing.xl を 32px で追加して」→ tokens_set(32 だけを渡すと単位がないためエラーになり、修正方法が返ります)

  • 「トークンをCSS変数に書き出して styles/tokens.css に保存して」→ tokens_export

  • 「src/app.css がトークンからずれていないか調べて」→ tokens_check_drift

ドリフト検知の出力例(実際の実行結果):

{
  "checked_file": "/tmp/sample.css",
  "matched": 2,
  "drift_count": 2,
  "drift": [
    {
      "value": "#0e7a6f",
      "line": 3,
      "kind": "color",
      "nearest_token": "color.primary",
      "nearest_value": "#0F766E"
    },
    {
      "value": "23px",
      "line": 5,
      "kind": "dimension",
      "nearest_token": "spacing.lg",
      "nearest_value": "24px"
    }
  ]
}

設計メモ

Anthropicのmcp-builderスキルの指針に沿っています。

  • ツール名はサービス接頭辞付きのsnake_case(tokens_list など)

  • 入力はZodスキーマで検証し、制約違反時は「次に何をすべきか」を含むエラーメッセージを返す

  • 読み取り系ツールには readOnlyHint / idempotentHint のannotationsを付与

  • 出力は structuredContent(構造化データ)とテキストの両方で返す

ライセンス

MIT License. 詳細は LICENSE を参照してください。

Available Tools

5 tools
tokens_check_driftDetect token drift in a CSS fileA
Read-onlyIdempotent

Scan a CSS file for hardcoded hex colors and px values, and compare each against the design tokens. Values that exactly match a token are reported as 'matched'; values that match no token are reported as 'drift', each with the nearest token as a fix suggestion. Returns { checked_file, matched, drift: [{ value, line, kind, nearest_token, nearest_value }] }. Use this after editing styles to keep code and design tokens in sync.

Inputs: css_path (required).

tokens_exportExport tokens to codeA
Idempotent

Export all design tokens in one of three formats: 'css' (CSS custom properties in a :root block), 'tailwind' (a Tailwind theme.extend fragment as CommonJS), or 'figma-variables' (a JSON shape close to Figma's Variables API with name/resolvedType/value). Returns { format, code }. Optionally pass out_path to also write the result to a file.

Inputs: format (required), out_path.

tokens_getGet one design tokenA
Read-onlyIdempotent

Get a single design token by its dot-path name, e.g. 'color.primary'. Returns { name, type, value }. If the token does not exist the error lists close matches; call tokens_list to see all names.

Inputs: name (required).

tokens_listList design tokensA
Read-onlyIdempotent

List all design tokens in the token file. Optionally filter by type (color, dimension, fontFamily, number) or by name prefix such as 'color.'. Returns { count, tokens: [{ name, type, value }] }. Use this first to discover token names before calling tokens_get or tokens_set.

Inputs: type, prefix.

tokens_setCreate or update a design tokenA
Idempotent

Create or update a design token. The value is validated against the token type before writing: color must be hex (#0F766E), dimension must have a unit (16px, 1.5rem), fontFamily must be a non-empty string, number must be numeric. Writes the token file in place and returns { name, type, value, created }. This is the only tool in this server that modifies the token file.

Inputs: name (required), type (required), value (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: listing, getting, setting, exporting, and drift-checking. No overlap.

    Naming Consistency5/5

    All tool names follow a consistent 'tokens_verb' pattern with snake_case, making the set predictable.

    Tool Count5/5

    5 tools is well-scoped for a design token server; each tool covers a core operation without redundancy.

    Completeness4/5

    The set covers CRUD except deletion, and includes export and drift detection. A delete token tool is missing, but the surface is otherwise complete for common workflows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that exposes your design system components and tokens to AI agents, preventing duplicate component creation and hardcoded token values.
      4 npm
      9
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI agents to access design system tokens and component contracts through MCP, reducing token usage and ensuring consistency.
      29
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI IDEs to query Figma design tokens, component specs, and audit issues via MCP tools, without cloud subscriptions.
      MIT