BrandKit MCP

BrandKit MCP

Give every AI tool access to your company's complete brand atomic system via the Model Context Protocol.

BrandKit MCP v2 is an open-source MCP server that exposes a company's complete brand atomic system -- verbal identity (positioning, audience, messaging, differentiation, concepts, voice) and visual identity (colors, typography, components, tokens, motion, assets) -- to Claude and other AI tools via the Model Context Protocol (MCP). It ships 18 read-only tools, one local write tool, and 14 resources. When an LLM helps build a website, app, or marketing asset, it has instant structured access to the exact brand language and visual rules it needs -- including a human-authored taste primer that carries the brand's instincts, not just its specs.

Quick Start

# 1. Install

npm install -g brandkit-mcp

2. Scaffold a new brand atomic system from the starter template

brandkit-mcp init

3. Edit the scaffolded files with your brand content

4. Wire into Claude Desktop (or any MCP-compatible client)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{

"mcpServers": {

"brandkit": {

"command": "brandkit-mcp",

"args": ["serve"]

}

}

}

init refuses to change an existing brandkit.config.yaml or brand_atomic_system/ unless --force is explicit. Force performs a clean replacement only for a regular single-link config and a real directory; symbolic links, hard-linked configs, and special-file destinations are rejected.

Repository Structure

A brand atomic system lives under a single / directory (default: ./brand_atomic_system):

<brand-root>/

├── readme.md ├── magic_trick.md # human-authored taste primer ├── brandkit.config.yaml # version: 2 ├── human/ # PDFs and human-only material (MCP ignores) │ └── *.pdf └── agent/ ├── verbal/ │ ├── positioning.md │ ├── audience.yaml │ ├── messaging.md │ ├── differentiation.md │ ├── concepts.md │ └── voice.md └── visual/ ├── colors_and_type.css ├── fonts/ ├── assets/ ├── components/ ├── tokens/ ├── motion/ │ ├── motion.json │ └── motion.css └── artifacts/ ├── web/ # override layer └── product/ # override layer

The human/ directory is intentionally ignored by the MCP server -- put PDFs, print specs, or any other human-only material there. Everything under agent/ is indexed and served.

MCP Tools Reference

BrandKit MCP exposes 18 tools to AI assistants:

The stdio transport also exposes sync_brand_docs, which updates brandkit.config.yaml, DESIGN.md, and PRODUCT.md. Network transports hide and refuse this write-capable tool by default.

Taste primer

Seven creative/verbal tools (get_brand_overview, get_positioning, get_audience, get_messaging, get_differentiation, get_concepts, get_voice) inject a _taste_primer field carrying magic_trick.md verbatim. get_magic_trick returns the primer directly without wrapping.

MCP Resources

BrandKit MCP exposes 14 brand:// URIs as MCP resources:

Configuration

The brandkit.config.yaml file at your project root controls BrandKit MCP:

version: 2

brand: name: Acme Corp description: Plumbing for builders. root: ./brand_atomic_system contexts: [base, web, product] ignore:

• human/

ingestion: maxFileBytes: 16777216 maxTotalBytes: 134217728 maxFiles: 1000 maxDepth: 16

Ignore entries are paths relative to brand.root. They match the named path and its descendants on directory boundaries, so human/ does not match humanity/.

Brand ingestion is bounded before file content is read. The defaults allow a maximum of 16 MiB per file, 128 MiB across all unique inputs, 1,000 unique files, and 16 path segments below brand.root. Fixed documents, discovered components and tokens, manifests, fonts, and image assets all share the same budget. Directory enumeration is also capped at four times the configured file limit, so a tree of empty or unsupported entries cannot create unbounded work before file counting. In-root symlink and hard-link aliases count once by canonical file identity; an alias cannot bypass containment or a limit. Exact boundaries are accepted and the next byte, file, or path segment fails startup with a brand-relative error. Large brands can raise these typed ingestion values up to the built-in safety caps (64 MiB per file, 512 MiB total, 10,000 files, and 64 segments); maxTotalBytes must be at least maxFileBytes.

version: 2 is required. A config file missing this field or declaring version: 1 causes the server to throw BrandkitV1ConfigError at startup.

Context System

BrandKit v2 supports three contexts:

Verbal content (agent/verbal/) has no context overrides -- it applies globally. Visual content can be overridden per context via the artifacts/ layer.

Migrating from v1

2.0.0 is a breaking release. The directory layout, context vocabulary, and tool surface have all changed. No automated migration is included -- the path mapping is manual:

Your brandkit.config.yaml must also be updated to declare version: 2 and use the new brand.root field. v1 configs throw BrandkitV1ConfigError at startup -- the server will not start until the config is updated.

Conventions

`magic_trick.md` is human-authored. The MCP reads it, but sync_brand_docs never writes to it. The taste primer is the brand's instincts -- it must stay human.

Token output formats. The get_tokens tool supports CSS custom properties, SCSS variables, Tailwind config, W3C Design Tokens, and flat JSON.

Brand files stay inside `brand.root`. Every fixed and discovered brand input is resolved and opened under the configured root. A symlink is accepted when its final target remains inside that root; symlinks and manifest paths that escape the root are ignored with a warning, and their content is never indexed or exposed through tools, resources, or preview pages.

The config must be a regular, single-link file. brandkit.config.yaml cannot be a symbolic link, hard link, directory, or other non-regular entry. The server binds config persistence to the file loaded at startup; if that path is replaced while the server is running, sync_brand_docs refuses to read or overwrite the replacement. Successful config updates use an atomic same-directory replacement and preserve existing permissions.

Transports. The server supports stdio (recommended for Claude Desktop), SSE (legacy HTTP), and Streamable HTTP (current MCP spec). Network transports remain unauthenticated when bound to loopback for local development. Before binding SSE or HTTP to any non-loopback host, set BRANDKIT_AUTH_TOKEN; clients must send it as Authorization: Bearer on every request.

Network transports are read-only by default, including loopback, standalone, and Vercel deployments. To deliberately expose sync_brand_docs over SSE or Streamable HTTP, start the CLI with brandkit-mcp serve --transport http --allow-write-tools (or set allowWriteTools: true in the programmatic startServer options). Treat this as privileged mode: authentication is still mandatory for non-loopback binds. Stdio keeps the intended local write workflow without this flag. Adapters without a writable config context never advertise the tool, even if privileged mode is requested.

Every network transport rejects untrusted Host and Origin headers with HTTP 403. Loopback listeners automatically trust loopback hostnames and origins, including IPv4, IPv6, and ephemeral ports. A concrete non-loopback server.host derives trust for that exact hostname. Wildcard bindings (0.0.0.0 or ::) fail at startup unless server.allowedHosts is explicit:

server:

transport: http host: 0.0.0.0 port: 3001 allowedHosts:

• mcp.example.com # hostname only; Host-header ports are ignored allowedOrigins:
• https://app.example.com

allowedOrigins entries are exact HTTP(S) origins, including the port when it is non-default. If the list is empty, requests without an Origin header remain valid for MCP clients, while a supplied Origin must use a trusted Host hostname. Configure allowedOrigins explicitly when a browser application is hosted on a different origin. IPv6 entries in allowedHosts use brackets, for example [2001:db8::10].

The preview UI is deliberately loopback-only and refuses any wildcard, LAN, or public bind host. It also applies the same Host and Origin validation to every page and static asset. Use the authenticated MCP HTTP transport when data must be available beyond the local machine.

Docker Compose

The default Compose service runs the supported Streamable HTTP tra