蓝湖 MCP

让 AI 直接读懂蓝湖。

快速开始

方式一：让 AI 帮你装（推荐）

把这句话发给你的 AI 助手（Claude Code / Cursor / 任何支持 MCP 协议的 AI）：

帮我通过 git clone 克隆仓库并安装蓝湖 MCP：https://github.com/yuanhuizang-cloud/lanhu-mcp

方式二：手动安装

前置：Git、Python ≥ 3.10。macOS / Linux 在终端运行：

git clone https://github.com/yuanhuizang-cloud/lanhu-mcp.git
cd lanhu-mcp
bash easy-install.sh

脚本自动安装依赖、引导填写 session、执行离线自检，再按选择接入客户端：

• Claude Code / Cursor：自动更新项目的 .mcp.json / .cursor/mcp.json，保留其他 MCP 服务。

• Codex：检测到 CLI 时自动注册；否则生成 codex-config.toml，供合并到用户目录的 .codex/config.toml。

• 其他客户端：使用生成的 mcp-config.json，不含登录凭据。

安装后重新打开 AI 客户端，提供蓝湖链接验证真实读取。离线自检只验证代码、配置读取和工具发现，不验证登录态是否有效。

在 PowerShell 中运行：

git clone https://github.com/yuanhuizang-cloud/lanhu-mcp.git
cd lanhu-mcp
.\easy-install.bat

无需激活虚拟环境或修改执行策略。需要重新填写 session 时运行：

.\easy-install.bat --configure --skip-deps

没有 Git 时，也可以在 GitHub 仓库选择 Code → Download ZIP，解压后进入项目目录运行对应安装脚本。

项目级 .mcp.json / .cursor/mcp.json 生成在克隆目录中。若要从其他前端工程使用，请按客户端的配置作用域，将生成的 mcp-config.json 中的服务条目合并到目标工程或全局配置。

配置

脚本根据 config.example.json 创建项目目录的 config.json。通常只需填写 session，其他项保持默认：

{
  "session": "粘贴你的 session 值",
  "request_timeout_seconds": 30,
  "max_redirects": 8,
  "download_max_mb": 64,
  "download_dir": "slices"
}

获取 session：浏览器登录 蓝湖 并打开设计稿 → Chrome 开发者工具（F12，macOS 为 ⌥⌘I）→ Application → Cookies → lanhuapp.com → session → 复制 Value，不带 session=。安装向导输入不回显；config.json 不提交到 Git，也不打进 Docker 镜像。

session 会过期。报「登录态失效」时，重新登录蓝湖并修改 config.json 的 session 后重试；每次工具调用重新读配置，本地无需重启客户端。也可以运行向导更新：

bash easy-install.sh --configure --skip-deps

MCP 使用 stdio，通常由客户端按需启动。手动排查入口：

bash run-stdio.sh

按 Ctrl+C 停止，再执行同一命令重启。离线协议自检：

.venv/bin/python scripts/check_mcp.py --check-config

.\run-stdio.bat

按 Ctrl+C 停止，再执行同一命令重启。离线自检：

.\.venv\Scripts\python.exe scripts/check_mcp.py --check-config

自动化安装可用 bash easy-install.sh --non-interactive --client project，使用前自行填写 config.json。依赖已就绪的离线重装可加 --skip-deps。

先复制 config.example.json 为 config.json 并填写 session（已运行安装脚本则无需重复）。安装并启动 Docker，在项目目录运行：

mkdir -p slices
LOCAL_UID="$(id -u)" LOCAL_GID="$(id -g)" docker compose run --build --rm lanhu-mcp

New-Item -ItemType Directory -Force slices | Out-Null
docker compose run --build --rm lanhu-mcp

Related MCP server: lanhu-mcp-server

工具与功能

使用示例

例 1：还原一个页面

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

例 2：按走查意见改样式

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

例 3：下载切图

你：把这个稿子的切图下载到我的前端工程 /绝对路径/my-app/assets 下。

能力对比与选型

核对日期：2026-10-21。以下按代码实现比较：本项目为当前实现；MrDgbot/lanhu-mcp 固定到 1c67536（包版本 2.0.2），dsphper/lanhu-mcp 固定到 6ded5bd（1.8.7）。社区后续版本可能变化。

强项、限制与适合的用户

当前能力边界

• 版本与选稿：没有历史版本列表或版本差异比较工具；URL 中的 versionId 虽会被解析，但不用于选择设计数据版本。带 tid 的单图链接应显式传入 design_name（建议用 ID），避免落到默认稿。多次工具调用之间也没有固定版本快照保证。

• 源数据与降级：图层依赖 json_url；DDS 仅作为补充，不会独立构建图层树。DDS 正常返回无资源时可只用图层源；DDS 请求抛错时仍会中断，尚不能保证自动降级。正常完成读取但无可用图层时返回空树与 note，不能仅据此认定为纯位图稿。

• 字段覆盖：已支持部分 Sketch / Figma / Photoshop 格式的根结构及基础样式映射，不保证所有源字段完整转换。例如 font.content 文本，以及没有 frame / bounds、只在图层顶层给出的几何字段，目前可能丢失。复杂效果与推断层级需要结合原始预览图核对。

• 输出范围：lanhu_get_design 中的 design_tokens 当前为 {}，annotations 为 []；评论需单独调用 lanhu_get_comments。没有直接生成组件工程、PRD / Axure 分析、自建留言发布或通知工具。

• 评论完整性：两路评论有分页上限；部分接口失败仍可能汇总为 status: "ok"，空列表也不能完全证明没有评论。画布评论的版本字段可能为空。

• 资源交付：列出变体不等于支持选择倍率 / 格式；当前下载使用默认 URL，不提供像素、哈希或目标倍率校验，也不提供远程客户端资源包交付。重复下载可能覆盖目标目录中已有的同名文件。

• 规模与耗时：图层无分页或区域筛选，切图顺序下载；较大设计稿可能返回较多内容。性能及设计还原精度需在目标项目上验证。

安全

• 凭据存储：session 仅保存在本地 config.json；安装脚本在 macOS / Linux 上设置权限为 600，并排除 Git 和 Docker 构建。不要提交或分享含真实凭据的配置。

• 会话域限制：请求头按蓝湖主域及子域判断是否携带 session；第三方 OSS / CDN 不带 Cookie，跳转到非蓝湖域名时剥离会话头。

• 下载边界：切图 / 预览图的初始 URL 校验 HTTPS、域名白名单与端口，默认大小上限为 64 MiB。当前未对每一跳重定向重复校验下载白名单，大小也在响应读取后检查，不能当作流式内存限制或完整的任意 URL 防护。

• 身份字段裁剪：评论输出只选取昵称、正文、时间、坐标、版本、回复与来源，不返回用户对象的手机号 / 邮箱 / open_id 等字段；不扫描或清除正文、昵称中可能出现的个人信息。

• 远端只读：七个工具不修改蓝湖设计与评论；lanhu_download_slices 会写本地文件，安装脚本会写本地配置。部分读取接口使用 POST，请求方法不代表修改远端数据。

• 运行依赖：两项直接运行依赖 mcp 和 httpx，无浏览器 / 数据库；安装时还会安装它们的传递依赖。

常见问题

• 跑不起来 / 找不到 Python：确认 Python ≥ 3.10 已安装，使用克隆方式时还需 Git；重新运行安装脚本，项目移动后也需重跑脚本更新绝对路径。

• 读不到图层树：检查返回的 note 和工具错误，可能涉及位图稿、权限、源数据格式或 DDS 请求失败；可先读取预览图核对，不保证所有异常都会返回空树。

• 报「未配置 session」：填写 config.json 的 session 字段，或运行一键安装向导。

• 报「登录态失效」：重新登录蓝湖并更新 config.json 的 session 后重试；本地无需重启，Docker 请重新创建容器。

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

• Docker 读不到 session：确认宿主机 config.json 已存在、只读挂载到 /app/config.json，并使用有读取权限的 UID/GID。

免责与许可证

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

• 运行与数据流：服务在你部署的机器上请求蓝湖及资源存储，并将设计数据、预览图、评论和资源地址返回你配置的 MCP 客户端；后续是否发送给云端模型取决于客户端和模型配置。本项目没有另设数据采集服务，不代表返回给客户端的数据始终留在本机。

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

• 许可证：MIT。