Skip to main content
Glama

Lanhu MCP Server

面向 蓝湖(Lanhu) 设计协作平台的模型上下文协议(Model Context Protocol,MCP)服务器。

让 LLM 和 AI 编码助手能够直接检视设计画板、提取像素级精确的 CSS 属性与图层层级结构,并下载可导出的素材资源——零视觉 Token 开销。

English • 简体中文


💡 为什么选择 Lanhu MCP?

当使用 AI 编程助手(Claude、Cursor、Copilot、Antigravity 等)实现 UI 设计时,直接传截图往往会带来:

  • 视觉模型的高 Token 成本

  • 定位不精确、边距靠猜测、颜色有偏差

  • 字体大小和行高被凭空捏造

  • 无法自动提取并下载 SVG/图片素材

Lanhu MCP Server 能将蓝湖的结构化设计规范直接解析为类型化数据树:

  • ⚡ 零视觉 Token 开销:使用纯 JSON 结构化数据,而不是沉重的截图。

  • 📐 像素级精确:精确的图层范围(x、y、width、height)、颜色(HEX/RGBA)、排版信息(fontSize、fontWeight、fontFamily、lineHeight)、圆角、填充、边框和阴影。

  • 🎨 智能素材提取:自动发现切图资源,提供 CDN 直接下载链接,并支持无损转换为现代 WebP 或 SVG 格式。

  • 🔄 可靠的认证机制:通过 Playwright 无头浏览器自动刷新 Token,实现会话的持久化管理。


Related MCP server: mcp-lanhu

✨ 核心特性

  • 团队与项目管理:轻松查询团队、工作区设计文件,并搜索项目。

  • 画板检视:列出画板(screens)、预览缩略图,并按名称搜索画板。

  • 深度图层标注:递归获取完整图层树,以及完善的 CSS/UI 样式属性。

  • 素材管线:将 SVG 矢量图和位图直接下载到本地工作区。

  • 自动化会话守护:无头 Playwright 脚本可在后台保持蓝湖会话有效,无需反复手动登录。


📋 环境要求

  • Python:>= 3.10

  • 包管理器:uv(强烈推荐)

  • MCP 客户端:Cursor、Claude Desktop、Claude Code、Antigravity、Windsurf、Cline、Codex、VS Code,或任何其他支持 MCP 的工具。


🚀 快速开始

1. 使用 uvx 运行(无需安装)

无需克隆仓库,即可直接运行 lanhu-mcp:

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

2. 从源码运行

# Clone the repository
git clone https://github.com/xinayida/lanhu-mcp.git
cd lanhu-mcp

# Sync environment and dependencies
uv sync

# Run the server (stdio mode)
uv run lanhu-mcp

🔐 身份认证

Lanhu MCP 通过浏览器会话 Cookie 连接 lanhuapp.com,并读取 ~/.lanhu/cookie(文件权限为 0600)。

方式一:自动登录与自动刷新(推荐)

运行随附的 Playwright 自动化脚本:

uv run scripts/refresh_cookie.py
  • 如果已登录:以无头模式验证会话、刷新 Token,并写入 ~/.lanhu/cookie。

  • 如果会话过期:自动打开 Chrome 窗口进行一次性登录(短信验证码或密码)。认证成功后保存会话并关闭浏览器。

定时任务提示:在 cron 任务中使用 --headless-only 运行,无需弹出窗口即可定期续期 Cookie:

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

方式二:在聊天工具中动态设置

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

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

手动获取 Cookie:

  1. 在 Chrome 中打开 lanhuapp.com,按 F12 打开开发者工具。

  2. 切到 Network 标签页,点击任何指向 lanhuapp.com 的请求。

  3. 在 Request Headers 中,复制包含 session 和 user_token 的完整 Cookie 字符串。

方式三:环境变量

在项目根目录创建 .env,或传入 LANHU_COOKIE:

cp .env.example .env
# Edit .env and set LANHU_COOKIE=session=...; user_token=...

🛠️ MCP 客户端配置

将 lanhu-mcp 添加到你常用的 MCP 客户端:

前往 Cursor 设置 -> MCP -> 添加新的 MCP Server:

  • 名称:lanhu

  • 类型: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 CLI:

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 MCP 扩展或设置添加:

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

🧰 可用工具

工具名称

描述

关键参数

lanhu_set_cookie

更新认证 Cookie 并持久化保存到 ~/.lanhu/cookie

cookie:包含 session 和 user_token 的字符串

lanhu_get_teams

获取用户团队列表(同时作为认证健康检查)

(无)

lanhu_get_projects

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

team_id:字符串

lanhu_search_projects

按关键词在团队内搜索项目

team_id:字符串,keyword:字符串

lanhu_get_screens

列出项目下所有画板(screens),包含尺寸与缩略图

project_id:字符串,team_id:字符串

lanhu_search_images

按关键词搜索画板

project_id:字符串,team_id:字符串,keyword:字符串

lanhu_get_annotations

⭐ 核心工具:获取完整图层树、CSS 样式、排版信息与素材资源

project_id:字符串,image_id:字符串,team_id:字符串

lanhu_get_assets

获取可导出的图像/图标资源及其下载链接

project_id:字符串,image_id:字符串,team_id:字符串

lanhu_download_asset

将资源下载到本地磁盘(支持 WebP 无损 / SVG / PNG)

asset_id、asset_name、download_url、format、save_dir


🧭 典型 AI 结对编程工作流

当要求 AI 智能体根据蓝湖设计稿实现 UI 时:

User: "Please implement the checkout screen from our Lanhu project and download necessary icons."

智能体将自动执行以下链路:

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. Generate Code CSS/HTML/React/Flutter]
    D --> F[6. lanhu_download_asset]

工具调用示例

# 1. Fetch team list
teams = lanhu_get_teams()
team_id = teams[0]["id"]

# 2. Get project list
projects = lanhu_get_projects(team_id=team_id)
project_id = projects[0]["id"]

# 3. Get artboards list
screens = lanhu_get_screens(project_id=project_id, team_id=team_id)
image_id = screens[0]["id"]

# 4. Extract full annotations
annotations = lanhu_get_annotations(
    project_id=project_id,
    image_id=image_id,
    team_id=team_id
)

# 5. Download icons/slices
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" # or "svg"
)

📦 标注数据结构

调用 lanhu_get_annotations 会返回结构化的 JSON:

{
  "id": "651234567890abcdef",
  "name": "Checkout Page",
  "width": 375.0,
  "height": 812.0,
  "thumbnail_url": "https://...",
  "layers": [
    {
      "id": "layer_01",
      "name": "Submit Button",
      "type": "rect",
      "bounds": { "x": 16.0, "y": 740.0, "width": 343.0, "height": 48.0 },
      "border_radius": 8.0,
      "opacity": 1.0,
      "visible": true,
      "fills": [
        { "type": "color", "color": "#0066FF", "opacity": 1.0 }
      ],
      "shadows": [
        { "x": 0.0, "y": 4.0, "blur": 12.0, "spread": 0.0, "color": "#0066FF33" }
      ],
      "children": [
        {
          "id": "layer_02",
          "name": "Button Label",
          "type": "text",
          "text": "Confirm & Pay",
          "bounds": { "x": 140.0, "y": 754.0, "width": 95.0, "height": 20.0 },
          "font": {
            "size": 16.0,
            "weight": "600",
            "family": "PingFang SC",
            "line_height": 20.0,
            "letter_spacing": 0.0,
            "color": "#FFFFFF",
            "text_align": "center"
          }
        }
      ]
    }
  ],
  "assets": [
    {
      "id": "asset_01:svg",
      "name": "icon_cart",
      "format": "svg",
      "download_url": "https://..."
    }
  ]
}

⚙️ 环境变量

变量

默认值

说明

LANHU_COOKIE

(空)

原始的 Cookie 字符串回退选项(session=...; user_token=...)

LANHU_DOWNLOAD_DIR

~/Downloads/lanhu_assets

下载资源的保存目录

LANHU_TIMEOUT

30

API HTTP 请求超时时间(秒)

LANHU_LOG_LEVEL

INFO

日志级别(DEBUG、INFO、WARNING、ERROR)


⚠️ 免责声明

本项目是一个独立开源工具,用于教学、测试和 AI 效率研究。它通过逆向的网页接口与蓝湖交互。使用本工具时,请遵守蓝湖的服务条款。作者不对任何误用行为负责。


📄 许可证

本项目基于 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