brandpilot-mcp

brandpilot-mcp

BrandPilot 的 MCP 服务：将品牌引入你的编码 Agent——列出品牌、读取设计的上下文和延续约定、安装其仓库规则包和设计令牌，并获取其设计系统套件；可直接在 Claude Code、Codex、Cursor、Claude Desktop 或任何其他 MCP 客户端中使用。

该软件包以两种模式之一运行：

• 使用工作区 API 密钥（BRANDPILOT_API_KEY）：通过 stdio 连接到托管的 BrandPilot MCP 的轻量代理，地址为 https://brandpilot.dev/api/mcp。所有 tools/list、tools/call、prompts/list 和 prompts/get 请求都会转发，并将响应原样返回，因此工具列表始终与 BrandPilot 当前提供的内容一致——新增工具无需更新软件包即可使用。
• 不使用密钥：通过 BrandPilot REST API v2 提供公开的设计系统工具，无需账号或密钥。

它不会接触数据库；任何可访问 brandpilot.dev 网络的机器都能运行它。需要 Node.js 20 或更高版本。

使用 API 密钥连接

在 BrandPilot 的 Settings, API keys 中创建工作区 API 密钥。密钥以 bp_live_ 开头。将下方的 bp_live_your_key_here 替换为你的密钥，并避免将密钥提交到文件中。

Claude Code

claude mcp add brandpilot --scope user -e BRANDPILOT_API_KEY=bp_live_your_key_here -- npx -y brandpilot-mcp

然后在 Claude Code 中运行 /mcp，确认 brandpilot 已连接，并询问“Ask BrandPilot who I am and list my brands”。

Codex

codex mcp add brandpilot --env BRANDPILOT_API_KEY=bp_live_your_key_here -- npx -y brandpilot-mcp

或在 ~/.codex/config.toml 中：

[mcp_servers.brandpilot]
command = "npx"
args = ["-y", "brandpilot-mcp"]

[mcp_servers.brandpilot.env]
BRANDPILOT_API_KEY = "bp_live_your_key_here"

若要避免将密钥写入文件，请在 shell 中导出 BRANDPILOT_API_KEY，并使用 env_vars = ["BRANDPILOT_API_KEY"] 替代 env 表。

Cursor

添加到 ~/.cursor/mcp.json（所有项目）或 .cursor/mcp.json（单个项目）：

{
  "mcpServers": {
    "brandpilot": {
      "command": "npx",
      "args": ["-y", "brandpilot-mcp"],
      "env": {
        "BRANDPILOT_API_KEY": "bp_live_your_key_here"
      }
    }
  }
}

任何其他 MCP 客户端

将 BRANDPILOT_API_KEY 放入环境变量中，并以 stdio 服务的方式运行 npx -y brandpilot-mcp。同样的配置结构也适用于 Claude Desktop 的 claude_desktop_config.json。

错误含义

消息	原因	解决方法
BrandPilot 拒绝了 API 密钥（HTTP 401）	密钥输入错误、已过期或已撤销	创建新密钥并重启服务
API 密钥没有此调用所需的权限（HTTP 403）	密钥缺少某个作用域（例如，只读密钥调用 finish_external_design）	使用具有该作用域的密钥
托管的 BrandPilot MCP 尚未启用（HTTP 404）	对应的 BrandPilot 实例尚未启用托管 MCP	暂时取消设置 BRANDPILOT_API_KEY 以使用公开工具，或检查 BRANDPILOT_MCP_URL
N 秒内未收到响应	托管调用耗时超过 BRANDPILOT_TIMEOUT_MS	重试；对于耗时较长的调用，请延长超时时间

密钥只会通过 Authorization 标头发送，绝不会被打印出来，包括在错误消息和 stderr 中。

工具

在 API 密钥模式下，工具和提示词由托管服务提供（品牌、设计上下文、仓库规则包、设计系统套件、将已完成的作品导入以供审核等）；当前列表见 https://brandpilot.dev/api/v2/mcp/tools 和 brandpilot.dev/docs。建议首先调用 whoami。

不使用密钥时，服务会通过 BrandPilot REST API v2 提供以下公开工具：

工具	身份验证	功能
list_public_systems	无	列出公开的设计系统（名称、显示名称、品牌颜色、状态、版本、v2 端点）
get_system_manifest	无	获取公开系统的完整采用清单：设计令牌、组件、页面、品牌资产、方向
export_system_tokens	无	导出系统的设计令牌（globals-css、colors-ts、spacing-ts、typography-ts、tailwind-theme、tailwind-v4、brand-manifest、dtcg）
get_adoption_brief	无	Markdown 入门文档：初始化设计软件包并开展一轮设计（为 Claude Code 使用 Design 画布，为其他 Agent 使用本地 HTML 草稿）

从 0.x 升级

1.0.0 是一次主要版本更新，因为移除了工具和一个变量。BrandPilot API v1 和每个设计的交接密钥将于 2026-12-15 停止响应（HTTP 410），因此届时所有 0.x 安装都将无法再进行无密钥调用；请在此之前升级。

• 公共工具现在调用 API v2（/api/v2/...，令牌使用 /api/v2/systems/{name}/export），而不再调用 API v1 和 /api/systems/export/{name}，并采用托管服务使用的 v2 名称：list_systems 现在改为 list_public_systems，get_system_adoption 改为 get_system_manifest，get_system_tokens 改为 export_system_tokens，get_agent_prompt 改为 get_adoption_brief。参数保持不变；export_system_tokens 还接受 tailwind-v4 和 dtcg。
• get_adoption_brief 返回新的 v2 简报：在 Design 画布上进行一轮设计（Claude Code），或生成本地 HTML 草稿（其他 Agent），而不是 Claude Design 步骤。
• 无密钥服务已移除 get_design_handoff、get_design_prompt_pack、import_design_artifacts 和 finish_external_design，也不再读取 DESIGNFLOW_HANDOFF_KEY（如果仍设置了该变量，只会打印一行提示你移除它）。它们的 v2 替代工具（get_design_context、get_design_brief、import_design_work、finish_design_import）由托管 MCP 提供：在 BrandPilot 中创建工作区 API 密钥（Settings, API keys），并设置 BRANDPILOT_API_KEY，参见使用 API 密钥连接。
• Claude Design 提示词包也随之停用：claude.ai/design 将于 2026-12-14 关闭。托管工具会返回设计上下文和仓库规则包，供你在自己的仓库中构建。
• brandpilot-mcp/catalog 现在只导出四个公共工具，且使用它们的 v2 端点。

环境变量

变量	默认值	用途
BRANDPILOT_API_KEY	（无）	工作区 API 密钥；启用代理模式
BRANDPILOT_MCP_URL	${BRANDPILOT_ORIGIN}/api/mcp	代理模式下的托管 MCP 端点。必须使用 https，本地主机除外
BRANDPILOT_TIMEOUT_MS	70000	代理模式下每个请求的超时时间（1000 到 600000）
BRANDPILOT_ORIGIN	https://brandpilot.dev	公共工具使用的源站，也是默认 BRANDPILOT_MCP_URL 的基础地址；可覆盖以指向本地开发服务器

本地开发

npm install
npm run build
npm test

端到端测试会让构建后的服务针对一个模拟源站运行；该源站会响应 API v2，并对所有 v1 路径返回 410。若要改为针对本地 BrandPilot 运行，请在执行 npm test 前设置 BRANDPILOT_E2E_ORIGIN=http://localhost:3005（任何提供 API v2 的源站均可）。

执行 npm link，然后配置 MCP 指向链接后的二进制文件，这是对照在线服务进行验证的最快方式：在 API 密钥模式下，确认 whoami 显示你的工作区名称；不使用密钥时，确认 list_public_systems 返回精选集合，且不包含任何私有内容。

请参阅 CHANGELOG.md 了解发行说明。