蓝湖 MCP

让 AI 直接读蓝湖设计稿、还原成代码。

把蓝湖的图层结构、每层 CSS、切图和走查评论交给 AI，自动生成 React / Vue / 小程序 / 原生代码——不用肉眼量间距、手抄色值、逐个下载切图。

第三方开源项目，与蓝湖（lanhuapp.com）官方无任何隶属、授权或背书关系；「蓝湖」仅为数据来源指称。读取蓝湖时使用你的个人登录态。

定位

不做「大而全」，只把**「读设计稿 → 还原 UI」**这一段做到最顺手。对标 Figma 官方 MCP 的能力面（链接解析 → 设计上下文 → 截图 → 切图），做成蓝湖版：

Related MCP server: lanhu-mcp-server

为什么选它

社区已有多款蓝湖 MCP（更早、star 更多、功能面更全），我们拼的不是功能数量，而是这条主链路上的精度与体验：

• 🎯 更准：用蓝湖官方结构化数据（json_url Sketch 源 + DDS props.style 补 CSS），而非解析 Sketch 文件的间接方案；每层输出框架无关的纯 CSS 对象。

• 💬 社区唯一走查评论：读设计稿批注（含回复、坐标、版本），把设计师的意见直接喂给 AI——这是「设计 → 代码」闭环里被所有人忽略的一环。

• 🪶 零浏览器、依赖最小：仅 mcp + httpx，一条命令装完，任何 CI / 容器 / 远程环境都能跑（对比 dsphper 需 Playwright + Chromium）。

• 🔒 安全更严谨：session 只发蓝湖域名、跨域重定向自动剥 Cookie；多数社区实现下载 CDN 切图时会把 Cookie 带出。

快速开始

最快：让 AI 帮你装。 把下面这段发给 Claude Code / Cursor：

帮我在当前目录安装并接入「蓝湖 MCP」：
1. python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
2. 把 .mcp.json 里的 lanhu 服务注册进你的 MCP 配置（或 claude mcp add lanhu -- .venv/bin/python src/server.py）
3. 运行 .venv/bin/python tests/test_transform.py 验证；然后让我提供一条蓝湖链接做真实读取

手动三步：

# ① 安装（需 Python 3.10+）
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt

# ② 认证（从蓝湖 Cookie 复制 session，详见「认证」）
export LANHU_SESSION='<你的 session>'

# ③ 接入
claude mcp add lanhu -- .venv/bin/python src/server.py

工具一览

7 个只读工具，覆盖「解析链接 → 列设计稿 → 读图层 → 截图对照 → 下切图 → 读走查」全链路：

design_name 可传名称 / id / 序号，留空取第一个。URL 参数别名全覆盖（tid/teamId/team_id、pid/project_id/projectId、image_id/imageId/img_id/imgId 等）。

怎么用

例 1：还原一个页面

你：用蓝湖 MCP 还原这个设计稿成 React 组件：https://lanhuapp.com/web/#/item/project/stage?tid=…&pid=…

AI 会自己走完 resolve_link → list_designs → get_design → get_screenshot → get_comments，然后产出对齐设计稿的组件代码。

例 2：按走查意见改样式

你：这个稿子有哪些走查意见？把主按钮改成评论里提到的那个色值。

AI 调 lanhu_get_comments 读到「主按钮改 #2563EB」，再定位对应节点改 css。

例 3：下载切图

你：把这个稿子的切图下载到 ./assets。

AI 调 lanhu_download_slices，图标 / 素材落到本地工程。

输出长什么样

lanhu_get_design 返回结构化、框架无关的图层树（每层 kebab-case CSS），AI 直接拼代码：

{
  "name": "购物车",
  "size": [375, 812],
  "schema_source": "sketch+dds",
  "layer_tree": [
    {
      "name": "结算栏",
      "type": "container",
      "css": { "left": 0, "top": 748, "width": 375, "height": 64 },
      "children": [
        {
          "name": "加入购物车",
          "type": "shape",
          "css": { "left": 16, "top": 758, "width": 343, "height": 44,
                   "background": "rgb(37,99,235)", "border-radius": 8 },
          "children": [
            { "name": "加入购物车", "type": "text",
              "css": { "font-size": 16, "font-weight": 600, "color": "rgb(255,255,255)" },
              "text": "加入购物车" }
          ]
        }
      ]
    }
  ]
}

详细使用

安装

• Python ≥ 3.10（macOS 自带版本可能过旧，可 brew install python@3.12）

• 依赖仅 mcp（2.x）、httpx（≥ 0.27）

git clone https://github.com/yuanhuizang-cloud/lanhu-mcp.git lanhu-mcp
cd lanhu-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

认证（读真实设计稿，必需）

1. 浏览器登录 lanhuapp.com，打开任意设计稿。

2. F12 → Application（应用） → Cookies → 点 lanhuapp.com → 复制名为 session 的 Value。

3. 存到本地（不回显、不写进配置、不进 Git）：

echo '粘贴你的 session 值' > ~/.lanhu_session
chmod 600 ~/.lanhu_session

优先级：LANHU_SESSION 环境变量 > ~/.lanhu_session 文件。session 会过期，报「登录态失效」时重复上面 3 步即可。

接入 AI 工具

• Claude Code：.mcp.json（或 claude mcp add lanhu -- .venv/bin/python src/server.py）

• Cursor：.cursor/mcp.json

• Codex：codex.config.example.toml 合并进 ~/.codex/config.toml

• Cline：command + args 填入 MCP 配置

通用配置（命令均为相对路径，在项目目录启动）：

{
  "mcpServers": {
    "lanhu": {
      "command": ".venv/bin/python",
      "args": ["src/server.py"]
    }
  }
}

架构与数据流

flowchart LR
    A[蓝湖链接] --> B[resolve_link 链接解析]
    B --> C[list_designs 设计稿列表]
    C --> D[get_design 读设计稿]
    D --> E[json_url Sketch 主树]
    D --> F[DDS store_schema_revise props.style 补 CSS]
    E --> G[transform.py 统一节点 + 每层 CSS]
    F --> G
    G --> H[AI 生成代码]
    D -.-> I[get_screenshot 截图]
    D -.-> J[get_slices / download_slices 切图]
    D -.-> K[get_comments 走查评论]

三级降级，任何情况不崩溃、不误导：

1. Sketch 源 + DDS CSS（最高精度）

2. 仅 Sketch 源

3. 纯位图稿 → 返回明确 note 提示

安全

• 凭据不外泄：session 只从 LANHU_SESSION 或 ~/.lanhu_session（chmod 600）读取，不写进代码 / 配置 / 提交物；仓库不含任何真实凭据。

• 会话域限制：session 只发 *.lanhuapp.com；切图等第三方域名（OSS / CDN）不带 Cookie，跨域重定向自动剥 Cookie。

• 隐私脱敏：评论只返回昵称 / 内容 / 时间 / 坐标 / 版本，不含手机号 / 邮箱 / open_id。

• 只读不改：7 个工具均为只读，不写蓝湖；唯一写操作是 download_slices 保存到本地目录。

• 最小依赖：仅 mcp + httpx，无浏览器 / 数据库。

与社区方案对比

已支持 / 边界

✅ 已支持：7 个工具、URL 别名兼容、detailDetach 单图、分享 / 邀请 / 短链解析、三级降级、评论脱敏。

⬜ 明确不做（聚焦主链路）：设计 tokens 独立输出、评论写回、蓝湖 D2C 代码直出、组件映射、PRD / Axure 文档、团队协作 / 留言板。

Docker 部署

cd lanhu-mcp
docker build -t lanhu-mcp .
docker run -i --rm -e LANHU_SESSION='你的 session 值' lanhu-mcp

接入 AI 工具用 docker.mcp.json（args 保留 -i）。镜像内以非 root 用户 mcp（uid 1000）运行，读不到宿主机 ~/.lanhu_session，用 -e LANHU_SESSION 传 session。

常见问题

• 跑不起来 / 找不到 .venv/bin/python：确认在项目目录运行；工具要求绝对路径时用 pwd 拼出 <项目路径>/.venv/bin/python 与 <项目路径>/src/server.py。

• 读不到图层树：该稿 json_url 无图层数据（纯位图稿），返回 note 提示而非报错。

• 报「未配置 session」：按「认证」配置后重启 AI 工具。

• 报「登录态失效」：session 过期，重新复制 Cookie 更新。

• 分享 / 邀请链接解析失败：确认账号已被邀请加入项目；或浏览器打开链接、登录后复制带 tid=…&pid=… 的正式链接。

• Docker 读不到 session：镜像读不到宿主机 ~/.lanhu_session，用 -e LANHU_SESSION=... 传入。

免责与许可证

• 第三方性质：独立开发者 / 开源社区维护；「蓝湖」仅为数据来源指称，读取时用你的个人登录态。

• 本地运行、不上传：所有读取与切图下载都在本机完成，不收集 / 不上传 / 不共享你的 session、设计稿数据或生成结果。

• 仅供学习与合法授权使用：只在你有权访问的账号 / 项目范围内使用。

• 许可证：MIT。