Tokencraft MCP Server

A Model Context Protocol (MCP) server for the Tokencraft Design Tokens API. This server allows AI assistants like Claude to interact with your design tokens workspace, tokensets, modes, and tokens.

Features

• 23 MCP Tools covering all Tokencraft API endpoints
• Full CRUD operations for workspaces, tokensets, modes, and tokens
• Export functionality in multiple formats (JSON, CSS, iOS, Android)
• Type-safe with TypeScript and Zod validation
• Bearer token authentication

Requirements

• Node.js 16.0.0 or higher
• Claude Desktop (or any MCP-compatible client)
• Tokencraft account with API token

Quick Start

1. Get Your API Token

1. Log in to your Tokencraft account at app.tokencraft.dev
2. Navigate to Settings → API Tokens
3. Click "New Token"
4. Name it "Claude Desktop" (or whatever you prefer)
5. Copy the token (you won't be able to see it again!)

2. Configure Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Option 1: Using NPX (Recommended)

No installation needed. Use an explicit version to avoid npx cache issues:

{
  "mcpServers": {
    "tokencraft": {
      "command": "npx",
      "args": ["-y", "@tokencraft/mcp-server@latest"],
      "env": {
        "TOKENCRAFT_API_TOKEN": "tkc_your_token_here"
      }
    }
  }
}

If you get ReadableStream is not defined: npx may be using a cached old version. Either clear the cache (rm -rf ~/.npm/_npx/*) or use @tokencraft/[email protected] explicitly in args.

To use the preview environment (preview.tokencraft.dev):

"env": {
  "TOKENCRAFT_API_TOKEN": "tkc_your_token_here",
  "TOKENCRAFT_BASE_URL": "https://preview.tokencraft.dev"
}

Option 2: Global Installation

If you prefer to install globally:

npm install -g @tokencraft/mcp-server

Then use in your config:

{
  "mcpServers": {
    "tokencraft": {
      "command": "tokencraft-mcp",
      "env": {
        "TOKENCRAFT_API_TOKEN": "tkc_your_token_here"
      }
    }
  }
}

3. Restart Claude Desktop

Close and reopen Claude Desktop for changes to take effect.

4. Verify It Works

In Claude, ask:

Can you list my Tokencraft workspaces?

Configuration

Environment Variables

| Variable | Required | Description | Default | |----------|----------|-------------|---------| | TOKENCRAFT_API_TOKEN | Yes | Your API authentication token | - | | TOKENCRAFT_BASE_URL | No | Base URL for the app (e.g. https://preview.tokencraft.dev for preview) | https://app.tokencraft.dev | | TOKENCRAFT_API_URL | No | Full API URL (overrides TOKENCRAFT_BASE_URL if both are set) | https://app.tokencraft.dev/api/v1 |

Available Tools

Workspaces (5 tools)

• list_workspaces - List all workspaces
• get_workspace - Get a specific workspace by ID
• create_workspace - Create a new workspace
• update_workspace - Update a workspace
• delete_workspace - Delete a workspace

Tokensets (5 tools)

• list_tokensets - List tokensets in a workspace
• get_tokenset - Get a specific tokenset by ID
• create_tokenset - Create a tokenset in a workspace
• update_tokenset - Update a tokenset
• delete_tokenset - Delete a tokenset

Modes (5 tools)

• list_modes - List modes in a tokenset
• get_mode - Get a specific mode by ID
• create_mode - Create a mode in a tokenset
• update_mode - Update a mode
• delete_mode - Delete a mode

Tokens (6 tools)

• list_tokens_by_tokenset - List all tokens in a tokenset (all modes)
• list_tokens_by_mode - List tokens for a specific mode
• get_token - Get a specific token with resolved value
• create_token - Create a token in a mode
• update_token - Update a token
• delete_token - Delete a token

Export (2 tools)

• export_tokenset - Export complete tokenset (all modes) in JSON/CSS/iOS/Android
• export_mode - Export a specific mode in JSON/CSS/iOS/Android

Example Prompts for Claude

Once configured, you can ask Claude things like:

"List all my workspaces"

"Create a new workspace called 'Mobile App Design System'"

"Show me all tokensets in workspace abc123"

"Create a color token called 'primary-blue' with value '#0066CC' in mode xyz789"

"Export my 'Colors' tokenset as CSS"

"List all tokens in the 'dark' mode"

"Update the primary-blue token to #0052A3"

Token Types

The following token types are supported:

• color - Color values
• dimension - Spacing, sizing values
• fontFamily - Font family names
• fontWeight - Font weights
• fontSize - Font sizes
• lineHeight - Line heights
• letterSpacing - Letter spacing
• duration - Animation durations
• cubicBezier - Timing functions
• number - Numeric values
• strokeStyle - Border styles
• border - Border composite
• transition - Transition composite
• shadow - Shadow composite
• gradient - Gradient composite
• typography - Typography composite

Development

If you're contributing to or modifying the MCP server itself:

# Clone the repository
cd mcp-server

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode for development
npm run watch

Note: For end users, use npx @tokencraft/mcp-server - no installation or build needed!

Project Structure

mcp-server/
├── src/
│   ├── index.ts          # Main MCP server entry point
│   ├── types.ts          # TypeScript type definitions
│   ├── client.ts         # HTTP client for API calls
│   └── tools/
│       ├── workspaces.ts # Workspace tools
│       ├── tokensets.ts  # Tokenset tools
│       ├── modes.ts      # Mode tools
│       ├── tokens.ts     # Token tools
│       └── export.ts     # Export tools
├── package.json
├── tsconfig.json
└── README.md

Error Handling

All tools include proper error handling. If an API request fails, the error message will be returned in the tool response with details about what went wrong.

Security

• Never commit your API token to version control
• Keep your claude_desktop_config.json secure
• Tokens can be revoked from your Tokencraft settings at any time

License

MIT

Support

For issues related to:

• This MCP Server: Open an issue in this repository
• Tokencraft API: Contact Tokencraft support
• Claude Desktop: Visit Anthropic's documentation