Brandsystem MCP — Brand Guidelines for AI

Use your brand guidelines with AI

`@brandsystem/mcp` turns the brand material you already have into context AI agents can use. Give it a website, PDF guide, Figma library, local files, or a Brandcode Studio brand. It produces a portable .brand/ runtime with design tokens, voice rules, provenance, and compliance checks.

Local-first. No account required. The default Core profile exposes 12 tools covering the complete adopt → use → check loop.

Start here

Install it for your agent, then ask: “How do I use my brand guidelines with AI?”

# Codex

npx @brandsystem/mcp install --client codex --write

Claude Code, Cursor, Windsurf, or Claude Desktop

npx @brandsystem/mcp install --client claude-code --write

Cline

npx @brandsystem/mcp install --client cline --write

Claude Desktop (one-click): download brandsystem-mcp- .mcpb from the latest GitHub release and double-click it (or drag it into Settings > Extensions). Claude Desktop asks for the folder that holds your .brand/ directory — no Node install or JSON editing needed.

install is a dry run unless you pass --write. Replace claude-code with cline, cursor, windsurf, or claude-desktop as needed. JSON-file targets preserve existing settings; Cline and Codex setup delegate to their official MCP commands so their current schemas remain authoritative. Agents can follow the compact installation guide without reading this entire README.

Already configured? Tell your agent:

Use my existing brand guidelines with AI. Start from this website/PDF/Figma library and show me what needs human confirmation.

What It Solves

AI tools default to category-average output because they have no brand context. Brand guidelines live in PDFs, Figma files, and people's heads — none of which AI tools can read at the moment of creation. The dominant failure mode isn't "broken output"; it's "correct but generic" — output that passes mechanical checks but reads like a competent generalist could have made it.

This MCP server is the authoring half of the "Two MCPs, One Brand" model. It extracts brand identity from live sources, compiles it into a .brand/ directory with structured governance (anti-patterns, proof-point status, voice rules, application rules) plus DTCG tokens, brand-runtime.json, and interaction-policy.json. That directory is the portable brand runtime — the artifact that travels with your brand from surface to surface.

• Claude Design reads the .brand/ directory natively when pointed at a governed repo
• Claude Code, Claude Desktop, Cursor, and Windsurf connect to this server directly over stdio and load brand-runtime.json at generation time
• ChatGPT and other remote-first clients consume the same runtime as an uploaded artifact (brand-report.html / brand-runtime.json) or via a remote MCP connection — see Compatibility
• @brandcode/mcp (the hosted Use MCP) serves the same runtime over HTTP for teams that want authenticated live reads at mcp.brandcode.studio/{slug}

With brand-runtime.json loaded, agent prompts collapse from 200-400 tokens of inline brand context to just the delta. First output is on-brand. No review bottleneck.

---

Quick Start

1. Add to your MCP config

Copy this into .mcp.json (Claude Code), .cursor/mcp.json (Cursor), or Windsurf MCP settings. Codex users can run npx @brandsystem/mcp install --client codex --write instead:

{

"mcpServers": { "brandsystem": { "command": "npx", "args": ["-y", "@brandsystem/mcp"] } } }

For project-level configs committed to a repository, pin a version ("@brandsystem/mcp@ ") so collaborators never auto-run an unreviewed release; npx @brandsystem/mcp install writes a pinned spec for you.

2. Create your brand system

Tell your AI tool:

Run brand_start with client_name="Acme Corp", website_url="https://acme.com", and mode="auto"

That single command extracts colors, fonts, and logo from the website, escalates to rendered or deeper multi-page extraction when the cheap pass is weak, compiles DTCG tokens, generates design-synthesis.json + DESIGN.md, and generates a portable HTML brand report -- all in under 60 seconds.

3. What you get

.brand/

brand.config.yaml ← brand name, source URLs, session state core-identity.yaml ← colors (with roles), fonts, logo specs tokens.json ← DTCG design tokens brand-runtime.json ← single-file brand context for any AI agent interaction-policy.json ← anti-patterns, voice constraints, never-say words design-synthesis.json ← spacing, radius, shadows, component signals DESIGN.md ← portable design brief (agent-readable) brand-report.html ← visual report (paste into any AI chat) assets/logo/ ← extracted logo files (SVG/PNG)

Load brand-runtime.json into any sub-agent's context. First output is on-brand. No per-prompt boilerplate.

4. Use it

Run brand_write for a social-graphic about "Q3 product launch"

The AI now has your full brand context — colors, typography, logo, anti-patterns, voice rules — and generates on-brand content.

Export to every tool's native format

Encode the brand once, then drop it into each tool in the format that tool already reads. brand_export writes to .brand/exports/:

Run brand_export with target="tailwind"

CSS targets are generated from the compiled DTCG tokens; brand strings are validated (hex colors, plausible font names, quoted families) so nothing extracted can break out of a declaration. Instruction targets (agents-md, cursor-rules) carry the provenance notice and keep brand values in a fenced data block.

5. Go deeper (optional)

Each session enriches brand-runtime.json. Stop at any point — Session 1 alone is valuable.

6. Share with your team

Run brand_brandcode_connect to save on Brandcode Studio

Your brand persists on brandcode.studio. Teammates pull the same brand into their tools. One source of truth.

---

What It Does

Session 1: Core Identity -- Extract colors, fonts, and logo from a website or Figma file. Compile into DTCG tokens, a structured design synthesis layer, a portable DESIGN.md, and an HTML report.

Session 2: Visual Identity -- Define composition rules, pattern language, illustration style, and anti-patterns through a guided interview. Anti-patterns become enforceable compliance rules.

Session 3: Messaging -- Audit existing website voice, then define perspective, voice codex (tone, vocabulary, AI-ism detection), and brand story through a guided interview.

Session 4: Content Strategy -- Build buyer personas, journey stages, editorial themes, and a persona x stage messaging matrix.

Each session builds on the previous. Stop anywhere -- you get value immediately.

Two Ways To Use It

Local-first MCP flow -- Start from a website or Figma file, build a .brand/ directory locally, and use it immediately in chat or code tools with no account required.

Brandcode Studio-connected flow -- Connect an existing hosted brand from Brandcode Studio, pull the packaged brand into .brand/, and keep it synced over time.

Two MCPs, One Brand

The .brand runtime is the product. Two MCPs serve it:

`@brandsystem/mcp` — Build (this package). Author and compile the .brand runtime locally. Extract from websites, Figma, and PDFs. Compile governance (anti-patterns, proof-point status, voice rules, application rules) plus DTCG tokens, brand-runtime.json, and interaction-policy.json into a single .brand/ directory. Portable, versionable, ready to commit to any repo.

`@brandcode/mcp` — Use (hosted). Connect authorized MCP clients to the live Full Brand Runtime at https://mcp.brandcode.studio/{slug} with Brandcode bearer-key auth. Agents fetch the current runtime, search approved knowledge, check drafts, retrieve package-safe assets, leave append-only review feedback, and, with explicit capture scope, queue taste captures for human review — no per-tool guideline copy, no stale snapshots, no canonical mutation from the MCP. Tagline: *"Your brand, live in every AI tool."*

Same .brand runtime artifact. Two consumption paths. Build authors it; Use serves it.

Phase 0 for Brandcode MCP is locked in specs/brandcode-mcp-phase-0-lock.md as the original 8-tool read/append-only surface. The current hosted implementation adds capture_taste as a scoped contribute-tier tool: it requires explicit capture scope, queues a review candidate for human review, and never promotes canon.

Hosted availability: Brandcode MCP is pre-release and available to approved clients only — it is not yet publicly launched or registry-listed. Brand data on the hosted service is client-owned; feedback is append-only; agent history is scoped and redacted. Deletion and export requests are handled through your Brandcode Studio contact. Until public launch, use @brandsystem/mcp for local build/sync, and Live Mode (brand_brandcode_live) for connected reads that refresh from the hosted runtime within a short cache TTL.

Maintainers can verify a hosted deployment end-to-end with the smoke harness (npm run smoke:hosted-mcp with BRANDCODE_MCP_SMOKE_URL and scoped test keys). It verifies MCP initialize, tools/list, the locked hosted tool order, core hosted tool calls, and read-only insufficient-scope behavior. It never hardcodes keys; mi