Skip to main content
Glama

蓝湖 MCP Server (Lanhu MCP)

专为 蓝湖 (Lanhu) 设计协作平台打造的 Model Context Protocol (MCP) 服务端。

让 AI 编码助手(Claude、Cursor、Antigravity、Windsurf 等)能够直接读取蓝湖设计图的完整图层树、获取像素级精确的 CSS 标注样式,并自动下载切图图标——全程无需消耗视觉 Vision Token。

简体中文 • English


💡 为什么需要 Lanhu MCP?

在日常使用 AI 辅助编写前端或移动端界面(React、Vue、Flutter、SwiftUI 等)时,通常依赖向大模型发送设计图截图。然而这种方式存在明显痛点:

  • Token 消耗巨大:高清截图会严重消耗模型的 Vision 上下文窗口;

  • 尺寸与颜色靠猜:模型对间距、边距、圆角与色值的识别存在幻觉和偏差;

  • 切图与图标无法自动化:模型无法直接将设计稿中的 SVG 图标或图片切图导出到本地工程。

Lanhu MCP Server 通过逆向解析蓝湖 Web 端数据协议,直接为大模型提供结构化的设计标注树:

  • ⚡ 零视觉 Token 消耗:纯 JSON 结构化数据传输,极大节省上下文空间与响应延迟。

  • 📐 像素级绝对精确:图层绝对坐标与尺寸(x, y, width, height)、精准色值(HEX/RGBA、设计规范色板名称 color_name)、线性与径向渐变(gradient)、字体排版(字号、粗细、行高、字距、复合文字分段 spans)、四角独立圆角(border_radii)、边框、阴影以及开箱即用的标准 css 样式字典全部精确提取。

  • 🎨 切图自动提取与 WebP 转换:自动识别导出切图并提供直链下载,位图切图默认自动转为现代高效的 WebP 格式,矢量图标支持原生 SVG 导出,免去手动切图和臃肿的 PNG。

  • 🔄 会话全自动化管理:内置基于 Playwright 的无头 Cookie 自动续期脚本,告别频繁手动登录。


Related MCP server: mcp-lanhu

✨ 核心特性

  • 团队与项目浏览:获取当前账号所在的团队列表、工作台设计项目,支持关键词搜索。

  • 画板/设计图检索:获取项目下的所有画板(Screen)信息、缩略图与尺寸信息。

  • 深度图层标注解析:递归解析完整图层树,还原组件嵌套层级,提供现成 CSS 属性、渐变色与多段文本样式。

  • 资源直下通道:一键下载设计图中的 SVG 矢量图与位图切图至本地指定目录,位图自动转为 WebP 格式。

  • 持久化认证续期:集成浏览器会话持久化与自动续期机制,稳定无感运行。


📋 环境要求

  • Python:>= 3.10

  • 包管理器:推荐使用 uv(快速且免配置)

  • MCP 客户端:Cursor、Claude Desktop、Claude Code、Antigravity、Windsurf、Cline、Codex、VS Code 等支持 MCP 协议的工具。


🚀 快速上手

方式一:使用 uvx 一键运行(推荐,免克隆)

无需手动下载仓库,直接通过 uvx 即开即用:

uvx --from git+https://github.com/xinayida/lanhu-mcp.git lanhu-mcp

方式二:从源码克隆运行

# 克隆仓库
git clone https://github.com/xinayida/lanhu-mcp.git
cd lanhu-mcp

# 同步安装虚拟环境与依赖
uv sync

# 启动 MCP 服务端(stdio 模式)
uv run lanhu-mcp

🔐 认证配置

Lanhu MCP 通过 Cookie 访问 lanhuapp.com。Cookie 默认安全存储于 ~/.lanhu/cookie(文件权限 0600)。

方式一:自动化登录与续期(最省心推荐)

运行项目内置的 Playwright 自动化续期脚本:

uv run scripts/refresh_cookie.py
  • 已登录状态:在后台以无头模式静默访问蓝湖,刷新 Session 并自动更新 ~/.lanhu/cookie。

  • 登录态过期:自动唤起 Chrome 窗口,等待用户进行一次登录(短信验证码或密码),登录成功后自动保存 Cookie 并关闭浏览器。

定时任务提示:可通过 --headless-only 参数配置到系统的 Cron 定时任务中定期静默刷新:

uv run scripts/refresh_cookie.py --headless-only

方式二:在对话中通过工具动态设置

在 AI 对话中直接调用 MCP 工具传入 Cookie:

lanhu_set_cookie(cookie="session=...; user_token=...")

手动获取 Cookie 方法:

  1. 在浏览器登录 lanhuapp.com,按 F12 打开开发者工具。

  2. 切换至 Network (网络) 面板,点击任意发往 lanhuapp.com 的请求。

  3. 在 Request Headers (请求标头) 中复制包含 session 和 user_token 的完整 Cookie 内容。

方式三:通过环境变量配置

在项目根目录创建 .env 文件或配置环境变量 LANHU_COOKIE:

cp .env.example .env
# 编辑 .env 文件,填写 LANHU_COOKIE=session=...; user_token=...

🛠️ MCP 客户端配置指南

选择您常用的 AI 编辑器/客户端进行一键接入:

打开 Cursor Settings -> MCP -> Add new MCP Server:

  • Name: lanhu

  • Type: command

  • Command:

    uvx --from git+https://github.com/xinayida/lanhu-mcp.git lanhu-mcp

或直接编辑配置文件 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}

编辑 claude_desktop_config.json(macOS 路径:~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}

使用 Claude Code 命令行直接添加:

claude mcp add lanhu uvx --from git+https://github.com/xinayida/lanhu-mcp.git lanhu-mcp

在 Antigravity 插件配置或 settings.json 中添加:

{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}

在 ~/.codeium/windsurf/mcp_config.json 中添加:

{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}

在 cline_mcp_settings.json 中配置:

{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

使用 Codex CLI 命令添加:

codex mcp add lanhu uvx "--from" "git+https://github.com/xinayida/lanhu-mcp.git" "lanhu-mcp"

或在 ~/.codex/config.toml 中配置:

[mcp_servers.lanhu]
command = "uvx"
args = ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]

在 VS Code 设置或 .vscode/mcp.json 中添加:

{
  "mcpServers": {
    "lanhu": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/xinayida/lanhu-mcp.git", "lanhu-mcp"]
    }
  }
}

🧰 工具清单与参数

工具名称

功能描述

核心参数

lanhu_inspect_url

⚡ 极速统一入口:智能解析任意蓝湖 URL,自动识别画板列表、单图详情、原型或分享链接

url: 蓝湖页面链接

lanhu_set_cookie

设置认证 Cookie 并持久化保存到 ~/.lanhu/cookie

cookie: 包含 session 和 user_token 的 Cookie 字符串

lanhu_get_teams

获取当前用户的团队列表(兼具认证连通性检测)

(无)

lanhu_get_projects

获取指定团队下的所有设计项目

team_id: 团队 ID

lanhu_search_projects

按名称关键词搜索团队内的项目

team_id: 团队 ID, keyword: 搜索关键词

lanhu_get_screens

获取指定项目下的画板列表(含尺寸和缩略图),支持直接传入 url

project_id / url, team_id (可选)

lanhu_search_images

按名称关键词搜索画板/设计图(已知项目 ID 时使用)

project_id: 项目 ID, team_id: 团队 ID (可选), keyword: 搜索关键词

lanhu_search_team_images

🔍 跨项目搜索:在指定团队内跨所有项目按名称搜索画板(无需事先知道项目 ID),支持并发与容错,返回直达单图链接与项目信息

team_id / url, keyword (可选), limit (默认 20)

lanhu_get_annotations

⭐ 核心工具:获取单张设计图的完整图层树与 CSS 标注数据,支持直接传入单图 url

project_id & image_id 或 url, team_id (可选)

lanhu_get_assets

获取画板中所有可导出的切图/图标直链资源列表,支持直接传入 url

project_id & image_id 或 url, team_id (可选)

lanhu_download_asset

下载切图到本地磁盘(位图自动转 WebP,矢量图保存为 SVG,具超大图安全防护)

asset_id, asset_name, download_url, format, save_dir

lanhu_batch_export_assets

批量导出画板中所有切图资源,并在目标目录自动生成 manifest.json 清单

project_id & image_id 或 url, save_dir (可选)

lanhu_get_design_tokens

🎨 设计系统:提取色板、字号、字重、圆角、阴影等全局规范 Token,支持导出 CSS/Tailwind/W3C 规范

project_id / url, image_id (可选), format (json/css/tailwind/w3c)

lanhu_get_layout_skeleton

📐 布局推断:自动将绝对定位图层树转为现代 Flexbox 流式骨架树与 Tailwind 类名

project_id & image_id 或 url

lanhu_list_product_documents

获取项目下的所有产品文档/Axure 原型文档列表,支持直接传入 url

project_id 或 url, team_id (可选)

lanhu_get_pages

获取 Axure 原型的完整页面目录树 (Sitemap) 与清单,支持直接传入 url

project_id & doc_id 或 url, team_id (可选)

lanhu_get_page_content

提取 Axure 页面的需求说明文本、黄色便签 (annotations) 与备注 (notes)

page_name, project_id & doc_id 或 url, team_id (可选)


🧭 典型 AI 编程工作流

方式一:直接提供蓝湖链接(最省心推荐 🚀)

直接将浏览器地址栏里的蓝湖链接发给 AI:

用户:“请帮我根据这个蓝湖画板实现登录页面:https://lanhuapp.com/web/#/item/project/detailDetach?pid=xxx&image_id=yyy”

AI 助手将直接调用 lanhu_inspect_url 或 lanhu_get_annotations(url=...),一步完成图层树与样式提取,无需多轮往返!

方式二:传统按项目逐步探索

graph LR
    A[1. lanhu_get_teams] --> B[2. lanhu_get_projects]
    B --> C[3. lanhu_get_screens]
    C --> D[4. lanhu_get_annotations]
    D --> E[5. 生成 CSS/HTML/React/Flutter 代码]
    D --> F[6. lanhu_download_asset 下载切图]

代码调用示例

# 极速单入口方式:
result = lanhu_inspect_url(url="https://lanhuapp.com/web/#/item/project/detailDetach?pid=xxx&image_id=yyy")

# 或传统分步方式:
# 1. 验证认证并获取团队
teams = lanhu_get_teams()
team_id = teams[0]["id"]

# 2. 获取项目列表
projects = lanhu_get_projects(team_id=team_id)
project_id = projects[0]["id"]

# 3. 获取画板列表
screens = lanhu_get_screens(project_id=project_id, team_id=team_id)
image_id = screens[0]["id"]

# 4. 获取核心图层标注与样式数据
annotations = lanhu_get_annotations(
    project_id=project_id,
    image_id=image_id,
    team_id=team_id
)

# 5. 下载页面切图/图标(位图默认保存为 webp,矢量图保存为 svg)
assets = lanhu_get_assets(project_id=project_id, image_id=image_id, team_id=team_id)
lanhu_download_asset(
    asset_id=assets[0]["id"],
    asset_name=assets[0]["name"],
    download_url=assets[0]["download_url"],
    format="webp" # 亦可指定 "svg"
)

📦 标注数据结构示例

调用 lanhu_get_annotations 返回的完整结构化 JSON:

{
  "id": "651234567890abcdef",
  "name": "收银台",
  "width": 375.0,
  "height": 812.0,
  "thumbnail_url": "https://...",
  "layers": [
    {
      "id": "layer_01",
      "name": "提交按钮",
      "type": "rect",
      "bounds": { "x": 16.0, "y": 740.0, "width": 343.0, "height": 48.0 },
      "border_radius": 12.0,
      "opacity": 1.0,
      "visible": true,
      "fills": [
        {
          "type": "gradient",
          "gradient": {
            "type": "linear",
            "angle": 180.0,
            "css": "linear-gradient(180deg, rgba(69,140,255,1) 0%, rgba(40,40,55,1) 100%)",
            "stops": [
              { "position": 0.0, "color": "#458CFF", "color_rgba": "rgba(69,140,255,1)" },
              { "position": 1.0, "color": "#282837", "color_rgba": "rgba(40,40,55,1)" }
            ]
          }
        }
      ],
      "borders": [
        {
          "width": 1.0,
          "style": "solid",
          "position": "center",
          "color": "#00C18C",
          "color_rgba": "rgba(0,193,140,1)",
          "color_name": "Brand/Primary",
          "css": "1.0px solid rgba(0,193,140,1)"
        }
      ],
      "css": {
        "width": "343px",
        "height": "48px",
        "background": "linear-gradient(180deg, rgba(69,140,255,1) 0%, rgba(40,40,55,1) 100%)",
        "border": "1.0px solid rgba(0,193,140,1)",
        "border-radius": "12px"
      },
      "children": [
        {
          "id": "layer_02",
          "name": "PriceText",
          "type": "text",
          "text": "7.2km",
          "bounds": { "x": 130.0, "y": 754.0, "width": 61.0, "height": 40.0 },
          "font": {
            "size": 32.0,
            "weight": "700",
            "family": "DINAlternate-Bold",
            "line_height": 40.0,
            "color": "#E9E6F8",
            "color_rgba": "rgba(233,230,248,1)",
            "spans": [
              { "text": "7.2", "size": 32.0, "weight": "700", "family": "DINAlternate-Bold", "color": "#E9E6F8" },
              { "text": "km", "size": 16.0, "weight": "700", "family": "DINAlternate-Bold", "color": "#E9E6F8" }
            ]
          },
          "css": {
            "width": "61px",
            "height": "40px",
            "font-family": "DINAlternate-Bold",
            "font-size": "32px",
            "font-weight": "700",
            "line-height": "40px",
            "color": "#E9E6F8"
          }
        }
      ]
    }
  ],
  "assets": [
    {
      "id": "asset_01:svg",
      "name": "icon_alipay",
      "format": "svg",
      "download_url": "https://..."
    },
    {
      "id": "asset_02:webp",
      "name": "banner_bg",
      "format": "webp",
      "download_url": "https://..."
    }
  ]
}

方式三:Axure 原型与 PRD 需求文档分析

除了 UI 标注外,蓝湖托管的 Axure 原型和产品文档(PRD)也是 AI 理解业务逻辑与交互需求的关键信息源。本工具采用纯轻量 API 逆向提取(无需任何浏览器进程),秒级提取原型目录结构与业务说明:

graph LR
    A[1. lanhu_list_product_documents] --> B[2. lanhu_get_pages]
    B --> C[3. lanhu_get_page_content]
    C --> D[4. AI 生成业务逻辑 / 交互状态 / 单元测试]

原型分析调用示例

# 1. 快捷单入口:直接查看原型文档概览(自动拉取页面目录)
result = lanhu_inspect_url("https://lanhuapp.com/web/#/item/project/productDoc?pid=xxx&doc_id=yyy")

# 2. 或手动提取单页面需求文本与交互便签
page = lanhu_get_page_content(
    url="https://lanhuapp.com/web/#/item/project/productDoc?pid=xxx&doc_id=yyy",
    page_name="登录页"
)
print(page["text_content"])   # 提取页面所有 DOM 文本与业务规则
print(page["annotations"])    # 提取黄色交互便签与备注

原型页面数据返回示例 (LanhuAxurePage)

{
  "id": "u0",
  "name": "登录页",
  "filename": "登录页.html",
  "type": "Wireframe",
  "folder": "用户中心",
  "path": "用户中心/登录页",
  "text_content": [
    "登录即代表同意用户协议与隐私条款",
    "用户名规则:支持手机号/邮箱,4-20位字符",
    "密码规则:6-20位字母数字组合"
  ],
  "annotations": [
    {
      "label": "登录按钮",
      "note": "未勾选协议时置灰禁用,勾选后变为高亮;点击后提交并展示 loading",
      "owner_id": "u12"
    }
  ],
  "notes": {
    "页面状态": "提供验证码登录与密码登录两种切换形态"
  }
}

方式四:设计系统 Tokens 与智能响应式布局骨架生成

无需人工从大量绝对坐标图层中寻找规律,通过内置的算法引擎一键完成规范提取与代码骨架转换:

graph LR
    A[蓝湖画板图层] --> B[lanhu_get_design_tokens]
    A --> C[lanhu_get_layout_skeleton]
    B --> D[CSS 变量 / Tailwind 配置 / W3C Tokens]
    C --> E[Flexbox 流式结构 + Tailwind 响应式代码]

1. 提取全局设计系统 Tokens

# 导出为原生 CSS 变量样式表
css_tokens = lanhu_get_design_tokens(url="https://lanhuapp.com/web/#/item/project/stage?tid=xxx&pid=yyy", format="css")

# 导出为 Tailwind 扩展配置
tailwind_config = lanhu_get_design_tokens(url="https://lanhuapp.com/web/#/item/project/stage?tid=xxx&pid=yyy", format="tailwind")

2. 智能推断 Flexbox 响应式布局骨架

# 自动将绝对坐标推断为语义化 HTML 标签 (header/button/h1/div) 与 Flex 流向 (flex-row / flex-col / gap / padding)
skeleton = lanhu_get_layout_skeleton(url="https://lanhuapp.com/web/#/item/project/detailDetach?pid=xxx&image_id=yyy")

3. 批量导出画板切图与生成清单

# 一键下载所有切图资源,并生成前端工程可直接引入的 manifest.json (含 import 语句)
res = lanhu_batch_export_assets(url="https://lanhuapp.com/web/#/item/project/detailDetach?pid=xxx&image_id=yyy", save_dir="src/assets")

⚙️ 环境变量配置说明

环境变量

默认值

说明

LANHU_COOKIE

(空)

蓝湖 Cookie 兜底配置(格式 session=...; user_token=...)

LANHU_DOWNLOAD_DIR

~/Downloads/lanhu_assets

切图资源下载保存的目标目录

LANHU_TIMEOUT

30

API 网络请求超时时间(秒)

LANHU_LOG_LEVEL

INFO

日志输出级别(DEBUG, INFO, WARNING, ERROR)


⚠️ 免责声明

本项目仅供个人学习、技术研究与 AI 辅助开发效率探索之目的,通过逆向分析 Web 接口实现。请在使用过程中严格遵守蓝湖服务条款。因使用本开源工具产生的任何风险与责任由使用者自行承担。


📄 开源许可

本项目基于 MIT License 协议开源。

Available Tools

9 tools
lanhu_download_assetA

下载指定的切图/图标到本地文件(位图默认自动转为 WebP 格式),返回保存路径。

需要先调用 lanhu_get_assets 获取资源的 download_url 等信息。

Inputs: asset_id (required), asset_name (required), download_url (required), format, +1 more.

lanhu_get_annotationsA

获取单张设计图的完整标注数据(最核心的工具)。

返回内容包含:

  • 所有图层的树形结构(位置、尺寸、颜色、字体、行高、圆角、阴影、边框等)

  • 文本图层的文字内容与字体样式

  • 可下载的切图/图标列表(含 download_url)

  • 画板尺寸与缩略图

Inputs: team_id (required), image_id (required), project_id (required).

lanhu_get_assetsB

获取设计图中所有可下载的切图/图标资源列表(含 svg/png 直链)。

Inputs: team_id (required), image_id (required), project_id (required). Returns: result

lanhu_get_projectsB

获取团队下的设计项目列表。

Inputs: team_id (required). Returns: result

lanhu_get_screensA

获取指定项目下的所有设计图(画板)列表,返回缩略图与尺寸信息。

Inputs: team_id (required), project_id (required). Returns: result

lanhu_get_teamsA

获取当前登录用户所在的团队列表。也可用于验证认证是否有效。

Inputs: no named parameters. Returns: result

lanhu_search_imagesC

在指定项目中按名称关键词搜索设计图。

Inputs: keyword (required), team_id (required), project_id (required). Returns: result

lanhu_search_projectsB

在团队下按名称关键词搜索项目。

Inputs: keyword (required), team_id (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 9 tools

    Disambiguation3/5

    Several tools have overlapping retrieval surfaces: get_projects vs search_projects and get_screens vs search_images are list-vs-search pairs, and get_annotations already includes downloadable assets that get_assets re-exposes. Descriptions clarify the intended use, but an agent could still select a broader tool when a narrower one is needed.

    Naming Consistency5/5

    All tools share the lanhu_ prefix and follow a consistent verb_noun snake_case pattern (set_, get_, search_, download_), with no mixed conventions or vague generic names.

    Tool Count5/5

    9 tools is well-scoped for a design-handoff/annotation server: auth, team/project navigation, screen listing, annotation retrieval, and asset download each have a focused tool.

    Completeness4/5

    The read-only workflow is well covered: authenticate, navigate teams/projects/screens, fetch annotations, and download assets. Minor gaps such as no direct get-by-id for a single project/screen (relying on list/search) and the redundant asset list inside get_annotations keep it from a perfect score.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI coding tools to read Lanhu design data and automate Design to Code, including project browsing, layer tree extraction, DDS semantic components, and code generation.
      14
      58 npm
      4
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI coding assistants to directly access Lanhu design drafts, generate frontend code, parse PRDs, and download design assets.
      3
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to read Lanhu design collaboration content: extracting and analyzing Axure prototype pages, downloading UI designs and slices, and converting design specs into HTML+CSS for implementation. It also provides a shared team message board so multiple AI tools can reuse requirement analyses and knowledge across projects.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to read Lanhu design specs — layer trees with per-layer CSS, screenshots, downloadable slices, and review comments — so they can restore UI and generate React/Vue/mini-program code without manual measuring or asset hunting.
      MIT