How do I use design-tokens-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@design-tokens-mcp list all color tokens" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

design-tokens-mcp

by N-Link-Lab

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

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.

ParametersJSON Schema

Name	Required	Description	Default
`css_path`	Yes	Path to the CSS file to scan

TDQS

A4.5/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint. The description adds substantial behavioral details: it reports matched and drift items with line, kind, nearest_token, and nearest_value, going well beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: 3 sentences front-loaded with the main action, then output structure and usage recommendation. No redundant text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With one parameter fully described in schema, no output schema, the description provides a clear output structure. For a simple scanning tool, this is complete and informative.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (css_path described), so baseline is 3. The description does not add extra parameter details beyond the schema, such as path expectations or file format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the action: scan a CSS file for hardcoded values and compare against design tokens. It clearly distinguishes from sibling tools (export, get, list, set) by focusing on drift detection.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises using this tool after editing styles to maintain sync, providing clear context for when to use it. It does not explicitly state when not to use it, but the guidance is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`format`	Yes	Output format
`out_path`	No	Optional file path to write the exported code to

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare idempotentHint: true, so the description's mention of optional file writing and return shape adds useful behavioral context. It does not describe error scenarios, but the idempotence mitigates concerns.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no wasted words. The first sentence front-loads the core purpose and formats; the second covers return and optional parameter. No fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 params, no output schema), the description covers the key aspects: formats, return shape, optional file output. It could mention that all tokens are exported, which it does ('Export all design tokens').

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, but the description adds significant value by explaining each format enum value (e.g., 'css' produces CSS custom properties in a :root block) and detailing the return structure, going beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Export' and clearly identifies the resource as 'all design tokens' in three formats, effectively distinguishing it from sibling tools like tokens_get (retrieve single) or tokens_set (modify).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the available formats and optional file writing, providing clear context for when to use this tool. It does not explicitly state when not to use it, but the sibling names imply the tool is for bulk export only, which is adequate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes	Token name as a dot path, e.g. 'color.primary'

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, so the safety profile is clear. Description adds value beyond annotations by specifying return format (name, type, value) and error behavior (close matches). No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with maximum information density. Critical details (purpose, example, return type, error behavior, sibling reference) are front-loaded. No fluff or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only tool with comprehensive annotations, the description covers all necessary aspects: what it does, how to use it, what it returns, and how to handle errors. No missing information given the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 100% coverage with a detailed description of the 'name' parameter. The description adds a concrete example ('color.primary') and hints at error behavior, but schema already fully documents the parameter structure and constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description explicitly states 'Get a single design token by its dot-path name' with a concrete example. It distinguishes from sibling tools by mentioning tokens_list and error handling for close matches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear when-to-use guidance with example dot-path, and when-not-to-use by suggesting tokens_list if the name is unknown. The error message behavior adds context for alternative action.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`type`	No	Only return tokens of this type
`prefix`	No	Only return tokens whose name starts with this prefix, e.g. 'color.'

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by stating it lists all tokens, optionally filters, and returns a specific structure { count, tokens: [...] }, which goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences: the first states the main purpose and optional filters, the second gives return format and usage guidance. No extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 optional params, no output schema, full annotations), the description covers all necessary aspects: functionality, filters, return structure, and usage intent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%; both parameters have descriptions. The tool description adds examples (e.g., 'color.' prefix) and repeats enum values, providing marginal extra clarity beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all design tokens in the token file.' and explicitly distinguishes from siblings by advising to use this first before tokens_get or tokens_set. It also specifies optional filters and return format.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance: 'Use this first to discover token names before calling tokens_get or tokens_set.' This directly tells when to use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description
`name`	Yes	Token name as a dot path, e.g. 'spacing.xl'
`type`	Yes	Token type; determines how the value is validated
`value`	Yes	Token value, e.g. '#0F766E', '32px', 'Noto Sans JP', '700'

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Description expands on annotations (idempotentHint=true) by clarifying it writes file in place and returns creation timestamp. Also documents validation behavior per type. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: first sentence states core purpose, second adds validation and return details. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Describes return shape and validation constraints. Lacks error handling details but is sufficient for a simple upsert tool without output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters, but description adds concrete examples (e.g., '#0F766E', '32px') and validation rules per type, helping the agent format values correctly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States 'Create or update a design token' with specific verb and resource. Explicitly distinguishes from siblings: 'This is the only tool in this server that modifies the token file.'

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not, but identifying it as the only modifying tool implies usage for token mutations. Also specifies validation rules to guide correct usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

5 tool updatesv1.0.0Jul 15, 2026
- First observedtokens_check_drift
- First observedtokens_export
- First observedtokens_get
- First observedtokens_list
- First observedtokens_set

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.6/5.0

Scored 2026-07-15 09:35 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.

Maintenance

ActivityMaintained

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

validator
dev.swatchdog
On-demand drift checks: declared CSS color, radius, spacing & type vs your own tokens or a pack
Design Tools Developer Tools
26
SupernovaOAuth
io.supernova
Access and maintain design system docs, tokens, components, skills, and contexts across any project.
Design Tools Documentation Access Developer Tools
1
design-system
app.zaklad
Build and manage your design system with AI: tokens, themes, components, icons, Figma and code.
Design Tools Developer Tools
2
Tseha A
io.tseha
Serves your design system and coding standards to coding agents, so they stop guessing.
Developer Tools Documentation Access
94

Related MCP Servers

ds-pilot
Design Tools Developer Tools
lyse-labs
A
license
Not graded
quality
C
maintenance
MCP server that exposes your design system components and tokens to AI agents, preventing duplicate component creation and hardcoded token values.
Updated 4 months ago (2026-05-13 14:09 UTC)
5 npm
9
MIT
eds-mcp-server
Design Tools Developer Tools
Edwson
A
license
B
quality
B
maintenance
Enables AI agents to access design system tokens and component contracts through MCP, reducing token usage and ensuring consistency.
Updated 6 days ago (2026-09-09 19:54 UTC)
29
MIT
ai-ready-ds-auditor
Design Tools Developer Tools
TJaraC
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.
Updated 6 months ago (2026-03-24 13:03 UTC)
MIT
Design Constraint Validator
Design Tools Testing & QA Tools
CseperkePapp
A
license
Not graded
quality
C
maintenance
Enables AI agents to validate design system constraints, including WCAG accessibility, token relationships, and consistency, through MCP tools like validate, explain, and suggest-fix.
Updated 3 months ago (2026-06-14 08:56 UTC)
40 npm
MIT