Brand-System/brandsystem-mcp

**@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?”**
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:
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
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.
5. Go deeper (optional)
| Session | What it adds | Command |
|---------|-------------|---------|
| 1. Core Identity | Colors, fonts, logo, tokens | brand_start (done above) |
| 2. Visual Identity | Composition, anti-patterns, illustration style | brand_deepen_identity |
| 3. Messaging | Voice, tone, never-say words, brand story | brand_compile_messaging |
| 4. Content Strategy | Personas, journey stages, themes | brand_build_personas |
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.