lanhu-mcp
A Model Context Protocol server that gives AI coding assistants structured access to Lanhu (蓝湖) design files — layer trees, pixel-accurate CSS, and exportable assets — with zero vision-token cost.
Authenticate: Set/persist a Lanhu cookie (
session+user_token) to~/.lanhu/cookie, and validate it via the team list.Browse & search: List teams, design projects, and artboards (with dimensions/thumbnails); search projects and screens by keyword.
Extract annotations: Get a design's full layer tree — positions, sizes, colors, fonts, gradients, radii, borders, shadows, text spans — plus ready-to-use CSS dicts.
Export assets: List downloadable slices/icons (SVG/PNG direct URLs) and download them to disk, auto-converting bitmaps to WebP.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@lanhu-mcp Get the CSS styles for the login button in the Home artboard"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
蓝湖 MCP Server (Lanhu MCP)
专为 蓝湖 (Lanhu) 设计协作平台打造的 Model Context Protocol (MCP) 服务端。
让 AI 编码助手(Claude、Cursor、Antigravity、Windsurf 等)能够直接读取蓝湖设计图的完整图层树、获取像素级精确的 CSS 标注样式,并自动下载切图图标——全程无需消耗视觉 Vision Token。
💡 为什么需要 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 方法:
在浏览器登录 lanhuapp.com,按
F12打开开发者工具。切换至 Network (网络) 面板,点击任意发往
lanhuapp.com的请求。在 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:
lanhuType:
commandCommand:
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"]
}
}
}🧰 工具清单与参数
工具名称 | 功能描述 | 核心参数 |
| ⚡ 极速统一入口:智能解析任意蓝湖 URL,自动识别画板列表、单图详情、原型或分享链接 |
|
| 设置认证 Cookie 并持久化保存到 |
|
| 获取当前用户的团队列表(兼具认证连通性检测) | (无) |
| 获取指定团队下的所有设计项目 |
|
| 按名称关键词搜索团队内的项目 |
|
| 获取指定项目下的画板列表(含尺寸和缩略图),支持直接传入 |
|
| 按名称关键词搜索画板/设计图(已知项目 ID 时使用) |
|
| 🔍 跨项目搜索:在指定团队内跨所有项目按名称搜索画板(无需事先知道项目 ID),支持并发与容错,返回直达单图链接与项目信息 |
|
| ⭐ 核心工具:获取单张设计图的完整图层树与 CSS 标注数据,支持直接传入单图 |
|
| 获取画板中所有可导出的切图/图标直链资源列表,支持直接传入 |
|
| 下载切图到本地磁盘(位图自动转 WebP,矢量图保存为 SVG,具超大图安全防护) |
|
| 批量导出画板中所有切图资源,并在目标目录自动生成 |
|
| 🎨 设计系统:提取色板、字号、字重、圆角、阴影等全局规范 Token,支持导出 CSS/Tailwind/W3C 规范 |
|
| 📐 布局推断:自动将绝对定位图层树转为现代 Flexbox 流式骨架树与 Tailwind 类名 |
|
| 获取项目下的所有产品文档/Axure 原型文档列表,支持直接传入 |
|
| 获取 Axure 原型的完整页面目录树 (Sitemap) 与清单,支持直接传入 |
|
| 提取 Axure 页面的需求说明文本、黄色便签 (annotations) 与备注 (notes) |
|
🧭 典型 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")⚙️ 环境变量配置说明
环境变量 | 默认值 | 说明 |
| (空) | 蓝湖 Cookie 兜底配置(格式 |
|
| 切图资源下载保存的目标目录 |
|
| API 网络请求超时时间(秒) |
|
| 日志输出级别( |
⚠️ 免责声明
本项目仅供个人学习、技术研究与 AI 辅助开发效率探索之目的,通过逆向分析 Web 接口实现。请在使用过程中严格遵守蓝湖服务条款。因使用本开源工具产生的任何风险与责任由使用者自行承担。
📄 开源许可
本项目基于 MIT License 协议开源。
Available Tools
9 toolslanhu_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
lanhu_set_cookieA
设置蓝湖认证 Cookie(并持久化到 ~/.lanhu/cookie)。
一般无需手动调用:Cookie 文件由 scripts/refresh_cookie.py 自动维护, MCP 启动时自动读取。仅在自动刷新不可用时,才需要从浏览器手动复制: DevTools → Network → 任一 lanhuapp.com 请求 → Request Headers → 复制完整 Cookie 头(须含 session 和 user_token)→ 传给本工具。 设置后可调用 lanhu_get_teams 验证是否生效。
Inputs: cookie (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Give AI agents your deeepSpace design system: components, tokens, styles and code mappings.
Serves your design system and coding standards to coding agents, so they stop guessing.
Search 700+ design layers and fetch the build prompt for HTML, Next.js, React, Vue and more.
Give your AI agents a design superpower. Generate, edit, and publish publication-grade decks, reports, landing pages, resumes, and marketing visuals directly within your agent workflow. Delivering frontier-level design quality at 3× the speed and 53× lower cost -from conversational prompt to live link or vector PDF in minutes.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables 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.1458 npm4MIT
- AlicenseAqualityCmaintenanceEnables AI coding assistants to directly access Lanhu design drafts, generate frontend code, parse PRDs, and download design assets.3MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseNot gradedqualityCmaintenanceEnables 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