@brandkity/mcp — BrandKity MCP Server

Model Context Protocol server for BrandKity — create and manage brand kits from any AI agent (Claude Desktop, Cursor, Windsurf, or any MCP-compatible client).

Current Version: 1.4.0 — Now with white-label branding support (Pro+)

Quick Start

1. Get an API Key

1. Sign in at brandkity.com

2. Go to Settings → API Keys

3. Click Generate New Key and copy the key (bk_live_...)

Requires a Pro or Agency plan for tool execution.

2. Configure Your AI Client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "brandkity": {
      "command": "npx",
      "args": ["-y", "@brandkity/mcp"],
      "env": {
        "BRANDKITY_API_KEY": "bk_live_your_key_here"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json:

{
  "mcpServers": {
    "brandkity": {
      "command": "npx",
      "args": ["-y", "@brandkity/mcp"],
      "env": {
        "BRANDKITY_API_KEY": "bk_live_your_key_here"
      }
    }
  }
}

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "brandkity": {
      "command": "npx",
      "args": ["-y", "@brandkity/mcp"],
      "env": {
        "BRANDKITY_API_KEY": "bk_live_your_key_here"
      }
    }
  }
}

3. Use It

Once configured, ask your AI agent to create a brand kit:

"Create a brand kit for Acme Corp with the accent color #E55B00. Add a Colors block with the primary palette (Orange Flame #E55B00, Midnight #1A1A2E, Canvas #FAF9F7) and a Typography block with Inter for headings and DM Sans for body. Upload the logos from /Users/me/acme/logos/."

Available Tools (22)

White-Label Branding (Pro+ Feature)

Customize your portal with custom favicon, social share image, and SEO metadata:

// Upload custom assets
const faviconUrl = await client.uploadFile('favicon.ico', faviconBuffer);
const ogImageUrl = await client.uploadFile('og-image.png', ogImageBuffer);

// Apply white-label branding
await client.updateKit('kit-id', {
  og_title: 'Acme Corp Brand Guidelines',
  og_description: 'Official brand assets and standards',
  custom_favicon_url: faviconUrl,
  og_image_url: ogImageUrl,
});

Fields:

• og_title (string, max 100 chars) — SEO title for social share

• og_description (string, max 300 chars) — SEO description

• custom_favicon_url (string) — CDN URL to favicon (ICO/PNG/SVG)

• og_image_url (string) — CDN URL to social share image (1200×630 px recommended)

Plan Requirements:

• Free/Starter: White-label fields are read-only

• Pro/Agency: Full read-write access

Environment Variables

Typical Workflow

1. get_workspace       → verify connection, check plan and storage
2. list_kits           → confirm kit doesn't already exist
3. create_kit          → returns kit_id
4. ensure_block        → idempotent: returns existing block_id or creates a new one (for each block type)
5. add_colors          → populate the Colors block
6. add_typography      → populate the Typography block
7. upload_file         → upload font/logo/cover files to workspace storage
8. upload_asset        → upload logos, images, videos into blocks
9. set_brand_story     → write the brand story in a rich_text block
10. set_block_note     → add usage guidance to any block
11. publish_kit        → make the portal live

Reliability Notes (v1.4.0)

• No duplicate blocks — ensure_block is idempotent. Re-running a workflow never creates duplicate blocks.

• Auto-retry on uploads — upload_asset and upload_file retry up to 3 times on network errors with exponential backoff.

• Size-aware timeouts — Upload timeout scales with file size (60 s base + 20 s per 10 MB, max 10 min). Large files like 64 MB video assets are handled reliably.

• Batch deduplication — upload_assets_batch silently skips duplicate file_path entries so the same file is never uploaded twice in one batch.

• Agent instructions — The server now provides operating rules to AI clients at connection time, reducing duplicate operations from AI agents automatically.

• White-label URL resolution — CDN URLs in white-label fields are automatically resolved to asset IDs server-side; agents don't need to manage asset IDs directly.

• Storage tracking — All file uploads are tracked per workspace for accurate quota enforcement.

License

MIT