lanhu-mcp
Lanhu MCP Server
面向 蓝湖(Lanhu) 设计协作平台的模型上下文协议(Model Context Protocol,MCP)服务器。
让 LLM 和 AI 编码助手能够直接检视设计画板、提取像素级精确的 CSS 属性与图层层级结构,并下载可导出的素材资源——零视觉 Token 开销。
💡 为什么选择 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-mcp2. 从源码运行
# 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:
在 Chrome 中打开 lanhuapp.com,按
F12打开开发者工具。切到 Network 标签页,点击任何指向
lanhuapp.com的请求。在 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"]
}
}
}🧰 可用工具
工具名称 | 描述 | 关键参数 |
| 更新认证 Cookie 并持久化保存到 |
|
| 获取用户团队列表(同时作为认证健康检查) | (无) |
| 获取指定团队下的设计项目 |
|
| 按关键词在团队内搜索项目 |
|
| 列出项目下所有画板( |
|
| 按关键词搜索画板 |
|
| ⭐ 核心工具:获取完整图层树、CSS 样式、排版信息与素材资源 |
|
| 获取可导出的图像/图标资源及其下载链接 |
|
| 将资源下载到本地磁盘(支持 WebP 无损 / SVG / PNG) |
|
🧭 典型 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://..."
}
]
}⚙️ 环境变量
变量 | 默认值 | 说明 |
| (空) | 原始的 Cookie 字符串回退选项( |
|
| 下载资源的保存目录 |
|
| API HTTP 请求超时时间(秒) |
|
| 日志级别( |
⚠️ 免责声明
本项目是一个独立开源工具,用于教学、测试和 AI 效率研究。它通过逆向的网页接口与蓝湖交互。使用本工具时,请遵守蓝湖的服务条款。作者不对任何误用行为负责。
📄 许可证
本项目基于 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