Content
# Lanhu MCP Server
Enable AI coding tools (Claude Code / Cursor / Cline, etc.) to directly read Lanhu design draft data, achieving Design to Code automation.
## Features
- **Project Browsing** — List team projects, design draft lists, and partition information
- **Accurate Design Data** — Obtain complete layer tree (@1x absolute coordinates, full style fill/border/shadow/typography)
- **DDS Semantic Component Tree** — Get Lanhu AI-identified UI component structure (NavBar / Avatar / Input / ImageText, etc.), including row/col layout and precise style
- **Code Generation** — Generate Vue 3 SFC or pure HTML code based on DDS semantic data
- **One-Click Download** — Extract official HTML/CSS code from DDS page using Puppeteer + download all sliced images and replace with local paths
- **Design Tokens** — Automatically extract design variables such as color, font, spacing, and corner radius
- **Resource Download** — Download cover images, sliced images, and exported images
## Installation
```bash
npm install -g dc-lanhu-mcp-server
```
Or use without installation:
```bash
npx dc-lanhu-mcp-server
```
## 30-Second Integration Guide
After global installation, copy the corresponding configuration for your AI coding tool:
### Claude Code (CLI)
```bash
claude mcp add lanhu-mcp \
-e LANHU_COOKIE="your cookie" \
-e LANHU_AUTHORIZATION="your token" \
-- dc-lanhu-mcp-server
```
### Cursor
Create `.cursor/mcp.json` in the project root directory:
```json
{
"mcpServers": {
"lanhu-mcp": {
"command": "dc-lanhu-mcp-server",
"env": {
"LANHU_COOKIE": "your cookie",
"LANHU_AUTHORIZATION": "your token"
}
}
}
}
```
### Codex (OpenAI)
```bash
codex mcp add lanhu-mcp \
-e LANHU_COOKIE="your cookie" \
-e LANHU_AUTHORIZATION="your token" \
-- dc-lanhu-mcp-server
```
### Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"lanhu-mcp": {
"command": "dc-lanhu-mcp-server",
"env": {
"LANHU_COOKIE": "your cookie",
"LANHU_AUTHORIZATION": "your token"
}
}
}
}
```
### VSCode Copilot Chat
Add to `.vscode/mcp.json`:
```json
{
"servers": {
"lanhu-mcp": {
"command": "dc-lanhu-mcp-server",
"env": {
"LANHU_COOKIE": "your cookie",
"LANHU_AUTHORIZATION": "your token"
}
}
}
}
```
### Cline (VSCode Extension)
Add to VSCode `settings.json`:
```json
{
"cline.mcpServers": {
"lanhu-mcp": {
"command": "dc-lanhu-mcp-server",
"env": {
"LANHU_COOKIE": "your cookie",
"LANHU_AUTHORIZATION": "your token"
}
}
}
}
```
### Cherry Studio / Other GUI Clients
Settings → MCP Servers → Add:
- **Type**: `stdio`
- **Command**: `dc-lanhu-mcp-server`
- **Env**: `LANHU_COOKIE=xxx`, `LANHU_AUTHORIZATION=xxx`
### Verification
Enter "**List My Lanhu Projects**" in any agent → return project list to confirm successful integration ✅
## Configuration
> **Only 2 fields required**: `LANHU_COOKIE` + `LANHU_AUTHORIZATION`.
> `tenantId` automatically discovered as `"0"` (verified to be available), `projectId` extracted from URL via `lanhu_set_project` or passed directly in tool parameters.
### 5 Configuration Methods Overview
| # | Method | Priority | Configuration Location | Applicable Scenario |
|---|------|--------|---------|---------|
| ① | Environment Variables | Highest | `process.env` | CI/CD, Docker, temporary testing |
| ② | `.mcp.json` | High | Project root directory | Team collaboration, configuration follows code |
| ③ | `.env` | Medium | Package installation directory | Local development, not submitted to git |
| ④ | `settings.json` | Low | `~/.claude/settings.json` | Personal developer, global effect |
| ⑤ | Interactive Guidance | Bottom line | Runtime input | First use, zero-configuration startup |
```
Priority: ① > ② > ③ > ④ > ⑤ (high priority overrides low priority)
```
### ① Environment Variables (Highest Priority)
Inject through process environment variables, suitable for CI/CD, Docker containers, or temporary testing:
```bash
# Method A: export and then start
export LANHU_COOKIE="your cookie"
export LANHU_AUTHORIZATION="your token"
npx dc-lanhu-mcp-server
# Method B: one-line command
LANHU_COOKIE="your cookie" LANHU_AUTHORIZATION="your token" npx dc-lanhu-mcp-server
# Method C: Docker / CI environment variables
# Set LANHU_COOKIE and LANHU_AUTHORIZATION in Dockerfile or CI configuration
```
Overrides values in all configuration files.
### ② `.mcp.json` Project-Level Configuration (Recommended for Team Use)
Create `.mcp.json` in the project root directory, configuration follows code, and can be submitted to git:
```json
{
"mcpServers": {
"lanhu-mcp": {
"type": "stdio",
"command": "npx",
"args": ["dc-lanhu-mcp-server"],
"env": {
"LANHU_COOKIE": "your cookie",
"LANHU_AUTHORIZATION": "your token"
}
}
}
}
```
**Advantages:**
- ✅ Only 2 fields, `tenantId`/`projectId` automatically discovered
- ✅ Configuration follows project, new members can use after cloning
- ✅ Can add to `.gitignore` to protect sensitive information
**Supported Paths:**
- `.mcp.json` (standard, Claude Code / Cursor universal)
- `.cursor/mcp.json` (Cursor-specific)
### ③ `.env` Local File
Create `.env` file in the `dc-lanhu-mcp-server` package installation directory:
```env
LANHU_COOKIE=your cookie
LANHU_AUTHORIZATION=your token
```
File permissions automatically set to `600` (only owner can read and write).
Suitable for: local development, don't want to pollute global configuration.
### ④ `settings.json` Global Configuration (Recommended for Personal Use)
Register through Claude Code CLI, configuration written to `~/.claude/settings.json`, universal for all projects:
```bash
# Register
claude mcp add lanhu-mcp \
-e LANHU_COOKIE="your cookie" \
-e LANHU_AUTHORIZATION="your token" \
-- npx dc-lanhu-mcp-server
# Verify
claude mcp list
# Use local installation path (faster startup)
claude mcp add lanhu-mcp \
-e LANHU_COOKIE="your cookie" \
-e LANHU_AUTHORIZATION="your token" \
-- node /path/to/dc-lanhu-mcp-server/dist/index.js
```
Also supports manual editing of `~/.claude/settings.json`:
```json
{
"mcpServers": {
"lanhu-mcp": {
"command": "npx",
"args": ["dc-lanhu-mcp-server"],
"env": {
"LANHU_COOKIE": "your cookie",
"LANHU_AUTHORIZATION": "your token"
}
}
}
}
```
### ⑤ Interactive Guidance (First-Time Bottom Line)
Without any configuration, first-time runtime automatically enters interactive guidance:
```bash
npx dc-lanhu-mcp-server
```
Guided process:
1. Prompt to input `LANHU_COOKIE`
2. Prompt to input `LANHU_AUTHORIZATION` (optional, press Enter to skip)
3. Prompt to input `tenantId` (optional, press Enter to skip → automatically discovered)
4. Paste Lanhu project URL (optional, press Enter to skip → set via `lanhu_set_project`)
5. Select write location (`.env` / `settings.json` / both)
6. Automatically save, no need to repeat input on next startup
### Configuration Priority
When multiple configuration sources coexist, load according to the following priority (local > global):
```
process.env → .mcp.json → .env → settings.json → Interactive Guidance
↑ ↑ ↑ ↑ ↑
Environment Variables Project-level configuration Local env Claude global First-time bottom line
```
**Example:**
- Both `.mcp.json` and `.env` exist → use `.mcp.json`
- Both environment variables and configuration files exist → use environment variables
- Only `settings.json` exists → automatically fill `.env`
## Obtain Lanhu Credentials
1. Log in to [Lanhu web version](https://lanhuapp.com)
2. Open Developer Tools with F12
3. Enter **Network** tab
4. Refresh page, select any Fetch/XHR request
5. In **Request Headers**, copy:
- `Cookie` → `LANHU_COOKIE` (required)
- `Authorization` → `LANHU_AUTHORIZATION` (recommended, some interfaces require)
> Only these 2 credentials are needed, `tenantId` and `projectId` do not need to be manually obtained.
## Usage Process
```
Configure credentials (2 fields) → Set project (URL automatically extracted) → Obtain design data
```
**Step 1: Configure Credentials** — Choose one of the 5 methods, only `LANHU_COOKIE` + `LANHU_AUTHORIZATION` required
**Step 2: Set Project** — Two options:
- Call `lanhu_set_project` with Lanhu URL, automatically extract `projectId` (recommended)
- Or pass `projectId` parameter directly in each tool call
**Step 3: Obtain Design Data** — Call tools like `lanhu_get_design_document`
```
# Example: dialogue in Claude Code
> "Obtain design draft from this Lanhu link and generate Vue component:
> https://lanhuapp.com/web/#/item/project/detailDetach?pid=xxx&project_id=xxx&image_id=yyy"
# MCP Server automatically completes:
# 1. Extract projectId and imageId from URL
# 2. autoDiscover() sets tenantId = "0"
# 3. Call getDesignDocument(imageId, projectId)
# 4. Return complete design data (layer tree + style + Design Tokens)
```
## MCP Tools
| Tool | Description |
|------|------|
| `lanhu_set_project` | Extract and set default projectId from Lanhu URL (subsequent tools do not need to pass) |
| `lanhu_list_projects` | List team projects/folders |
| `lanhu_get_designs` | Obtain design draft list under project |
| `lanhu_get_design_detail` | Obtain design draft details (size, preview image, version) |
| `lanhu_get_design_document` | Obtain complete precise structured design data (core) |
| `lanhu_get_annotations` | Obtain annotation data (layer tree) |
| `lanhu_get_preview` | Obtain preview image URL |
| `lanhu_get_tokens` | Extract Design Tokens |
| `lanhu_get_sectors` | Obtain project partition information |
| `lanhu_get_dds_schema` | Obtain DDS semantic UI component tree |
| `lanhu_generate_code` | Generate Vue / HTML code based on DDS data |
| `lanhu_download_design` | One-click download design draft (DDS code + sliced images) |
| `lanhu_download_cover` | Download design draft cover image |
| `lanhu_download_image` | Download any image to local |
## Environment Variables
| Variable | Required | Description |
|------|------|------|
| `LANHU_COOKIE` | Yes | Lanhu login Cookie |
| `LANHU_AUTHORIZATION` | No | Authorization Token (some interfaces require) |
| `LANHU_TENANT_ID` | No | Tenant ID (automatically discovered if not configured, default `"0"` verified to be available) |
| `LANHU_PROJECT_ID` | No | Default project ID (not configured, passed through tool parameters or set using `lanhu_set_project`) |
| `CHROME_PATH` | No | Chrome path (required for `lanhu_download_design`, automatically detected by default) |
## Testing
### Method 1: MCP Inspector (Recommended)
[MCP Inspector](https://github.com/modelcontextprotocol/inspector) is an official debugging tool that provides a Web UI to directly call Tools:
```bash
# Set environment variables
export LANHU_COOKIE="your cookie"
export LANHU_AUTHORIZATION="your token"
# Start Inspector
npx @modelcontextprotocol/inspector node dist/index.js
```
Browser will open `http://localhost:5173`, allowing you to:
- View all registered Tools
- Manually call each Tool and view return results
- Debug input parameters
### Method 2: Direct Testing in Claude Code
```bash
# 1. Add MCP Server
claude mcp add lanhu-mcp -e LANHU_COOKIE="your cookie" -- node $(pwd)/dist/index.js
# 2. Start Claude Code, direct dialogue testing
claude
# Then say in dialogue:
# "List my Lanhu projects"
# "Obtain design draft xxx data"
```
### Usage Process
1. **Configure Credentials** — `.mcp.json` only needs `LANHU_COOKIE` + `LANHU_AUTHORIZATION`
2. **Set Project** (choose one):
- Call `lanhu_set_project` with Lanhu URL, automatically extract `projectId`
- Or pass `projectId` parameter directly in each tool call
3. **Obtain Design Data** — Call tools like `lanhu_get_design_document`
```
# Example dialogue process:
> "Obtain design draft from this Lanhu link: https://lanhuapp.com/web/#/item/project/detailDetach?pid=xxx&project_id=xxx&image_id=yyy"
# MCP Server automatically:
# 1. Extract projectId and imageId
# 2. Call getDesignDocument(imageId, projectId)
# 3. Return complete design data
```
### Method 3: Quick Verification with Command Line
```bash
# Confirm Server can start normally (will wait for stdio input)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0.1.0"}}}' | LANHU_COOKIE="your cookie" node dist/index.js
```
### Method 4: Development Mode + Inspector
```bash
# Use tsx to run directly, modify code without rebuilding
npx @modelcontextprotocol/inspector npx tsx src/index.ts
```
## Error Logs
Server will automatically capture all exceptions and record to log files for easy troubleshooting.
**Log Location:**
```
~/.lanhu-mcp/error.log
```
**Monitoring Content:**
- `TOOL_ERROR` — Tool call failure (including tool name, parameters, complete stack)
- `UNCAUGHT_EXCEPTION` — Unhandled exceptions
- `UNHANDLED_REJECTION` — Unhandled Promise rejection
- `SIGTERM` / `SIGINT` — Process exit signals
**Common Commands:**
```bash
# Real-time view (recommended, open a terminal window during debugging)
tail -f ~/.lanhu-mcp/error.log
# View entire content
cat ~/.lanhu-mcp/error.log
# View last 50 lines
tail -50 ~/.lanhu-mcp/error.log
# Paginated view (press q to exit, / to search)
less ~/.lanhu-mcp/error.log
```
# Check Errors for a Specific Tool
grep "lanhu_download_design" ~/.lanhu-mcp/error.log
# Count Error Occurrences
grep -c "TOOL_ERROR" ~/.lanhu-mcp/error.log
# Clear Logs
> ~/.lanhu-mcp/error.log
# Open with Editor
code ~/.lanhu-mcp/error.log # VSCode / Cursor
**Log Format:**
```
[2026-07-15T02:02:50.582Z] TOOL_ERROR [lanhu_get_design_document]: Failed to get details: Image not exist
Error: Failed to get details: Image not exist
at LanhuClient.getDesignDetail (...)
at ...
Args: {
"imageId": "invalid-image-id-12345",
"projectId": "b27d22f6-..."
}
────────────────────────────────────────────────────────────────────────────────
```
Each log entry includes: timestamp / type / tool name / error message / call stack / call arguments.
## Project Structure
```
src/
├── index.ts # MCP Server entry (initial configuration guide + stdio launch)
├── client.ts # Lanhu API client (layer parsing, DDS, download)
├── tools.ts # MCP Tools registration
├── dds-codegen.ts # DDS → Vue / HTML code generator
├── dds-puppeteer.ts # Puppeteer extracts DDS official code + image download
└── types.ts # type definitions
```
## References
- [Lanhu Official Website](https://lanhuapp.com)
- [MCP Protocol Specification](https://modelcontextprotocol.io)
- [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
- [MCP Inspector](https://github.com/modelcontextprotocol/inspector) — Official debugging tool
- [dsphper/lanhu-mcp](https://github.com/dsphper/lanhu-mcp) — Community reference implementation
- [Puppeteer](https://pptr.dev) — DDS code extraction dependency
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available