@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.3 — MCP now available on Starter, Pro, and Agency plans

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_...)

Available on Starter, Pro, and Agency plans. Sign up free to explore, then upgrade Starter or above to run tool calls.

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)

| Tool | Description | |------|-------------| | Workspace | | | get_workspace | Get workspace info (plan, kit count, storage) | | Files | | | upload_file | Upload any local file to workspace storage → returns a public URL | | list_files | List workspace files with type filter and pagination | | Kits | | | list_kits | List all brand kits (filter by draft/published/all) | | create_kit | Create a new kit → returns kit_id | | get_kit | Get a kit with all blocks and content | | update_kit | Update kit settings (name, color, template, logo_url, cover_image_url, white-label fields) | | publish_kit | Publish a kit → returns public URL | | unpublish_kit | Unpublish a kit (reverts to draft) | | Blocks | | | list_blocks | List all blocks in a kit with IDs and types | | ensure_block | Idempotent — returns existing block_id or creates a new block (preferred over add_block) | | add_block | Add a block unconditionally (use ensure_block instead to prevent duplicates) | | update_block | Update block name/visibility | | delete_block | Permanently delete a block and all its content | | Content | | | add_colors | Add color swatches to a Colors block | | add_typography | Add font entries to a Typography block | | set_brand_story | Set rich text content (brand story, tone of voice) | | set_block_note | Set the editorial note displayed above any block | | Upload | | | upload_asset | Upload a local file into a block (logos, visuals, videos, etc.) with auto-retry | | upload_assets_batch | Upload multiple local files into the same block; deduplicates by file path | | upload_kit_logo | Upload and set the kit's header logo | | upload_cover_image | Upload and set the kit's cover image |

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: White-label fields are read-only; MCP tool calls return 403
• Starter/Pro/Agency: Full MCP access; white-label fields are read-write on Pro/Agency

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | BRANDKITY_API_KEY | Yes | — | Personal Access Token (bk_live_...) | | BRANDKITY_API_URL | No | https://brandkity.com | API base URL (for local dev) |

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