蓝湖 MCP 快速上手手册（Claude + Codex）

目标：只需提供蓝湖 Cookie（文档中也称 Token），即可快速拉起 lanhu-mcp，并在 Claude/Codex 中调用。

0. Cookie 获取方式

1.登录蓝湖网页，打开开发者工具。

2.进入 Network，选择任意 Fetch/XHR 请求。

3.在 Request Headers 复制完整 Cookie。

1. 3 分钟跑通（安装 + 启动 + 接入）

1.1 先设置路径变量

export PROJECT_DIR="$HOME/path/to/your-project"   # 你的业务项目目录export LANHU_MCP_DIR="$HOME/lanhu-mcp-main"     # lanhu-mcp 本地目录

1.2 一次性安装（首次机器执行）

# 基础检查python3 --versionnpm -vgit --version
# 拉取代码[ -d "$LANHU_MCP_DIR" ] || git clone https://github.com/dsphper/lanhu-mcp.git "$LANHU_MCP_DIR"cd "$LANHU_MCP_DIR"cp -f .env.example .env
# 写入蓝湖 Cookieexport LANHU_TOKEN='这里替换成你的蓝湖Cookie'if grep -q '^LANHU_COOKIE=' .env; then  sed -i '' "s|^LANHU_COOKIE=.*|LANHU_COOKIE=\"${LANHU_TOKEN}\"|" .envelse  printf '\nLANHU_COOKIE="%s"\n' "${LANHU_TOKEN}" >> .envfi
# 安装依赖python3 -m venv venvsource venv/bin/activatepython -m pip install -U pip setuptoolspip install -r requirements.txtpython -m playwright install chromium

1.3 每次启动服务（推荐方式）

cd "$PROJECT_DIR"mkdir -p data/messages
export LANHU_COOKIE="$(awk -F'"' '/^LANHU_COOKIE=/{print $2}' "$LANHU_MCP_DIR/.env")"export SERVER_PORT=8000
"$LANHU_MCP_DIR/venv/bin/python" "$LANHU_MCP_DIR/lanhu_mcp_server.py"

启动成功日志应包含：

Uvicorn running on http://0.0.0.0:8000

1.4 接入 Claude/Codex MCP

# Claudeclaude mcp remove lanhu >/dev/null 2>&1 || trueclaude mcp add --transport http lanhu "http://localhost:8000/mcp?role=测试&name=Lucas"claude mcp list
# Codexcodex mcp remove lanhu >/dev/null 2>&1 || truecodex mcp add lanhu --url "http://localhost:8000/mcp?role=测试&name=Lucas"codex mcp list

Bash

1.5 快速验证

lsof -iTCP:8000 -sTCP:LISTEN -n -Pcodex mcp list

---

2. 标准流程

第 1 节是最短路径；本节是详细版。若两处文字有重复，统一以本节命令为准。

2.1 环境要求

• git

• Python 3.10+（建议 3.11）

• Node.js + npm

2.2 为什么推荐在业务目录启动服务

lanhu-mcp 会写入相对路径 data/messages。若历史上用过 sudo 启动，容易出现目录归属为 root，导致普通用户写入失败。推荐固定在 $PROJECT_DIR 启动，并确保：

cd "$PROJECT_DIR"mkdir -p data/messages

Bash

2.3 Cookie 配置约定

• lanhu-mcp 实际读取的是 .env 里的 LANHU_COOKIE

• 本文所有"Token"都按 Cookie 字符串处理

写入方式已在 1.2 给出，后续只需复用 1.3 里的读取逻辑。

---

3. lanhu-requirements-doc Skill 使用

3.1 Skill 路径

• Claude：<项目根目录>/.claude/skills/lanhu-requirements-doc/SKILL.md

• Claude：<项目根目录>/.claude/skills/lanhu-requirements-doc/template.md

• Codex：$CODEX_HOME/skills/lanhu-requirements-doc/SKILL.md

• Codex：$CODEX_HOME/skills/lanhu-requirements-doc/template.md

3.2 单页面扫描（带 pageId）

触发条件：URL 包含 docId + product + pageId。

Claude：

/lanhu-requirements-doc https://lanhuapp.com/web/#/item/project/product?...&versionId=...&docId=...&pageId=...

Codex：

$lanhu-requirements-doc https://lanhuapp.com/web/#/item/project/product?...&versionId=...&docId=...&pageId=...

输出文件：需求文档-[项目名]-[页面名]-[YYYYMMDD].md

3.3 全版本页面扫描（不带 pageId）

触发条件：URL 包含 docId + product，但不带 pageId。

Claude：

/lanhu-requirements-doc https://lanhuapp.com/web/#/item/project/product?...&versionId=...&docId=...

Codex：

$lanhu-requirements-doc https://lanhuapp.com/web/#/item/project/product?...&versionId=...&docId=...

如果手里是单页链接但要扫全量，删除 URL 中 pageId（通常也删掉 image_id、parentId）。

3.4 Codex 无 Slash 技能入口时（等价提示词）

请按 <项目根目录>/.claude/skills/lanhu-requirements-doc/SKILL.md 的规则处理以下蓝湖链接：1) 先判断是邀请链接、PRD单页、PRD全文档还是UI设计；2) 使用 lanhu MCP 的对应工具读取并分析；3) 按 <项目根目录>/.claude/skills/lanhu-requirements-doc/template.md 输出完整中文需求文档；4) 保存为 需求文档-[项目名]-[YYYYMMDD].md（若是单页则带页面名）。蓝湖链接：<在这里粘贴>

---

4. 按症状查错（实战版）

症状	常见原因	处理
failed to persist config.toml（codex mcp add时）	当前执行环境不能写 ~/.codex/config.toml	在可写权限下执行 codex mcp add ...
lanhu_get_pages /lanhu_get_ai_analyze_page_result调不通，或出现 user cancelled MCP tool call	codex exec 内层沙箱影响 MCP 调用链路	排障阶段用 codex exec --dangerously-bypass-approvals-and-sandbox ...验证
PermissionError: data/messages/...json	data/messages 不可写（常见于历史 sudo）	在 $PROJECT_DIR 启动并 mkdir -p data/messages，避免继续 sudo启动
bind 0.0.0.0:8000 operation not permitted	端口监听权限受限	使用允许监听端口的执行权限启动
Python < 3.10	版本不满足依赖	升级到 3.11 并重建 venv
ResolutionImpossible	旧环境依赖冲突	删除 venv后重建并重装依赖
Playwright EACCES	浏览器依赖安装权限不足	优先修复目录权限并重建；sudo quickstart仅临时兜底

---

5.蓝湖MCP支持

功能名称	功能类别	功能描述
lanhu resolve invite link	项目协作	解析并加入项目 。该功能允许开发者或AI客户端通过蓝湖的邀请链接，自动解析项目信息并加入到指定的蓝湖项目中，省去手动查找和申请的步骤，快速建立协作环境。
lanhu get pages	设计获取	获取页面列表 。用于查询指定蓝湖项目或设计稿中包含的所有页面。开发者可以通过该命令了解设计稿的结构，例如一个App设计稿中包含"登录页"、"首页"、"个人中心页"等。
lanhu get ai analyze_page_rel	AI分析	分析页面关联关系 。调用AI能力分析蓝湖项目中各个页面之间的逻辑跳转关系或流程。通常用于生成用户流程图（User Flow），帮助理解产品交互逻辑，可能与蓝湖自带的设计图连线功能相关。
lanhu get designs	设计获取	获取设计稿列表 。用于获取指定项目或团队下的所有设计稿文件。这是进行后续操作（如获取页面、切图）的起点，方便AI了解当前有哪些可用的设计资源。
lanhu_get_ai_analyze_design	AI分析	AI分析设计稿 。针对单张特定的设计稿，利用AI进行深度分析。可能包括识别设计稿中的UI组件（如按钮、卡片）、布局结构、颜色规范等，为代码生成或设计走查提供依据。
lanhu get design_ slices	资源获取	获取设计切图 。用于获取指定设计稿或页面中所有标记好的切图资源（如PNG、SVG、WebP格式）。开发者可以利用此功能让AI自动下载所需图标和图片，无需手动逐一导出。
lanhu_say	评论协作	发送评论 。在蓝湖的设计稿上针对某个元素或页面发送评论。可用于向设计师提问、反馈开发问题或确认设计细节，将沟通记录与具体设计关联。
lanhu_say_list	评论协作	查看评论列表 。获取指定设计稿或页面上的所有评论历史。方便开发者和设计师回顾沟通过程，追踪待解决问题，避免信息遗漏。
lanhu_say_detail	评论协作	查看评论详情 。查看某一条特定评论的详细内容、回复记录以及@的相关成员信息，深入理解沟通上下文。
lanhu say_edit	评论协作	编辑评论 。允许用户修改已发送的评论内容，用于修正错误、补充信息或更新讨论要点，保持沟通的准确性和时效性。
lanhu say_delete	评论协作	删除评论 。根据评论ID删除已发送或已解决的评论，用于管理设计稿上的讨论内容，保持界面整洁。
lanhu get members	团队管理	获取成员列表 。查询当前蓝湖项目或团队中的所有成员信息。这对于自动识别设计师、产品经理或开发负责人，或者在进行协作（如@成员）时非常有用。

6. 验收清单

• 服务日志出现 Uvicorn running on http://0.0.0.0:8000

• claude mcp list 可见 lanhu

• codex mcp list 可见 lanhu

• 能用蓝湖链接成功执行一次 lanhu-++requirements++ -doc