目标：只需提供蓝湖
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 --version
npm -v
git --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
# 写入蓝湖 Cookie
export LANHU_TOKEN='这里替换成你的蓝湖Cookie'
if grep -q '^LANHU_COOKIE=' .env; then
sed -i '' "s|^LANHU_COOKIE=.*|LANHU_COOKIE=\"${LANHU_TOKEN}\"|" .env
else
printf '\nLANHU_COOKIE="%s"\n' "${LANHU_TOKEN}" >> .env
fi
# 安装依赖
python3 -m venv venv
source venv/bin/activate
python -m pip install -U pip setuptools
pip install -r requirements.txt
python -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
# Claude
claude mcp remove lanhu >/dev/null 2>&1 || true
claude mcp add --transport http lanhu "http://localhost:8000/mcp?role=测试&name=Lucas"
claude mcp list
# Codex
codex mcp remove lanhu >/dev/null 2>&1 || true
codex mcp add lanhu --url "http://localhost:8000/mcp?role=测试&name=Lucas"
codex mcp list
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 callcodex exec内层沙箱影响 MCP 调用链路排障阶段用codex exec --dangerously-bypass-approvals-and-sandbox ...验证PermissionError: data/messages/...jsondata/messages不可写（常见于历史sudo）在$PROJECT_DIR启动并mkdir -p data/messages，避免继续sudo启动bind 0.0.0.0:8000 operation not permitted端口监听权限受限使用允许监听端口的执行权限启动Python < 3.10版本不满足依赖升级到 3.11 并重建venvResolutionImpossible旧环境依赖冲突删除venv后重建并重装依赖PlaywrightEACCES浏览器依赖安装权限不足优先修复目录权限并重建；sudo quickstart仅临时兜底
5.蓝湖MCP支持
功能名称功能类别功能描述lanhu resolve invite link项目协作解析并加入项目。
该功能允许开发者或AI客户端通过蓝湖的邀请链接，自动解析项目信息并加入到指定的蓝湖项目中，省去手动查找和申请的步骤，快速建立协作环境。
lanhu get pages设计获取获取页面列表。
用于查询指定蓝湖项目或设计稿中包含的所有页面。
开发者可以通过该命令了解设计稿的结构，例如一个App设计稿中包含“登录页”、“首页”、“个人中心页”等。
lanhu get ai analyze_page_relAI分析分析页面关联关系。
调用AI能力分析蓝湖项目中各个页面之间的逻辑跳转关系或流程。
通常用于生成用户流程图（User Flow），帮助理解产品交互逻辑，可能与蓝湖自带的设计图连线功能相关。
lanhu get designs设计获取获取设计稿列表。
用于获取指定项目或团队下的所有设计稿文件。
这是进行后续操作（如获取页面、切图）的起点，方便AI了解当前有哪些可用的设计资源。
lanhu_get_ai_analyze_designAI分析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