Self-Host Lanhu MCP and Connect with Localtonet

What Lanhu MCP provides and how the deployment works

Lanhu MCP is a self-hosted Model Context Protocol server for working with Lanhu design delivery and requirement material. A compatible AI assistant can use the MCP tools to retrieve supported project information instead of relying on users to copy requirements, screenshots, annotations, and design references into every conversation.

The current upstream project describes requirement-document extraction, Axure page analysis, design previews, source parameters, image assets, image slicing, and shared team knowledge workflows. Requirement analysis can be approached from development, testing, or quick-exploration perspectives. The server supplies source information and visual material, while the connected AI model and user remain responsible for interpreting that material and checking conclusions against the original requirement or design.

Lanhu MCP v1.8.6 adds focused visual inspection for ambiguous Axure requirements. After retrieving pages, a client can use lanhu_inspect_requirement_region with exactly one supported anchor: rendered text through query, a stable block_id, a long-page tile_id, or an explicit source rectangle defined by coordinates. Repeated text can return candidate previews for the vision model to distinguish. The tool does not perform OCR and does not infer meaning from layer names.

The same v1.8.6 release keeps the established full screenshot and adds full-width long-page strips that split vertically. Its release notes specify source strips of at most 960 pixels high with 96 pixels of overlap by default. Screenshot cache schema 4 rebuilds tile metadata once after an upgrade. These are release-specific behaviors, not general performance or accuracy guarantees. Review the Lanhu MCP v1.8.6 release notes before relying on them.

HTTP and stdio are different operating models

Use stdio when the MCP client runs on the same computer and can launch a command with arguments. The repository includes run-stdio.sh and run-stdio.bat for that pattern. The client owns the child process and communicates through standard input and output, so there is no HTTP listener to tunnel.

Use HTTP when Lanhu MCP must remain running independently as a network service. With the documented example configuration, the endpoint is http://localhost:8000/mcp. Localtonet applies only to this HTTP deployment. Installing with Docker or Python does not by itself create an HTTP listener. The listener exists only when the service is started with HTTP transport and the selected host and port are reachable.

The upstream repository is the primary location for current project behavior and installation files. Consult the Lanhu MCP repository and README alongside this tutorial when selecting a release.

Prerequisites and security preparation

Docker users need Git, Docker, and a working Docker Compose command. Current installations commonly expose Compose as docker compose, while an older installation may use docker-compose. Source users need Git and Python 3.10 or newer. The project explicitly notes that Python 3.9, including the version historically bundled with some macOS systems, does not meet its requirement.

Check the interpreter before creating a virtual environment:

python3 --version

On Windows, the available launcher may instead be:

python --version

You also need an authorized Lanhu account with access to the projects the server will read. The required LANHU_COOKIE is obtained from an authenticated browser session. Log in to Lanhu, open the browser developer tools, inspect an authenticated request to Lanhu, and copy the complete Cookie request-header value into the server's protected environment configuration. The upstream Lanhu cookie tutorial provides the project-specific procedure.

Reserve local TCP port 8000 unless you intend to change SERVER_PORT. Check that another program is not already listening on that port. If our Localtonet client will run on another device, that device must be able to reach the chosen server address and port over the private network. A loopback listener such as 127.0.0.1 is reachable only from the same network namespace or host.

Install Lanhu MCP with Docker Compose

Docker Compose is the upstream project's recommended manual deployment path. It isolates the application dependencies and provides a repeatable build and startup workflow. The commands below follow the current repository instructions. Additional deployment details are maintained in the upstream Lanhu MCP deployment guide.

git clone https://github.com/dsphper/lanhu-mcp.git
cd lanhu-mcp

cp .env.example .env

copy .env.example .env

docker compose up -d --build

Inspect service state and logs after startup:

docker compose ps
docker compose logs

A running container does not prove that the application initialized successfully. Review the logs for a missing cookie, dependency failure, browser setup problem, port conflict, or application exception. Redact credentials, private project names, internal paths, and request data before sharing logs.

Understand Docker listener binding

Container networking changes the meaning of a bind address. The documented example uses SERVER_HOST=0.0.0.0, which lets the process accept traffic through the container's network interface. Changing the process inside the container to 127.0.0.1 can prevent traffic arriving through Docker's published port from reaching it.

This does not mean the host port must be exposed to every LAN interface. Container binding and host port publication are separate controls. Review the repository's current Compose file and the effective Docker port mapping. If you need host-only access, constrain the host-side publication using a configuration supported by your Docker deployment, then verify it from both the host and another LAN device. This guide does not provide an unverified replacement Compose file.

Install Lanhu MCP from source with Python 3.10+

A source installation is useful when you want to inspect or modify the code, cannot use Docker, or need to integrate the process with an existing Python-oriented service manager. The repository supplies installer scripts for Linux, macOS, and Windows. It also documents a manual virtual-environment procedure.

Installer-script path

git clone https://github.com/dsphper/lanhu-mcp.git
cd lanhu-mcp

bash easy-install.sh

easy-install.bat

The current shell installer can select package and browser-download mirrors and fall back to other configured sources. The upstream documentation names PIP_INDEX_URL, PLAYWRIGHT_DOWNLOAD_HOST, and PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST as overrides. Leave these unset unless your network or package policy requires a different source.

Manual virtual-environment path

On Linux or macOS:

python3 -m venv venv
./venv/bin/python -m pip install -e .
./venv/bin/python -m playwright install chromium
cp .env.example .env

On Windows:

python -m venv venv
venv\Scripts\python.exe -m pip install -e .
venv\Scripts\python.exe -m playwright install chromium
copy .env.example .env

Edit .env and set LANHU_COOKIE before startup. The project also documents supplying the cookie through the process environment. Avoid entering a real cookie directly into a command that will be retained in shell history. A restricted environment file or managed secret facility is safer for persistent operation.

Source-host loopback binding

A source process runs directly in the host network namespace. If the Localtonet client and Lanhu MCP are on the same host, a loopback-only source listener can reduce LAN exposure, provided the current Lanhu MCP release accepts the selected SERVER_HOST value and the client can reach it. Test the actual listener after changing the value.

If our client runs on another device, a source process bound to 127.0.0.1 will not be reachable from that device. In that topology, the service needs an appropriate private interface binding and host firewall policy, or both components should be moved to the same host. Do not confuse this source-host behavior with the container requirement to accept traffic through Docker's network interface.

Configure the server and its HTTP listener

The required variable is LANHU_COOKIE. The repository also documents settings for the listener, data directory, outbound timeout, browser viewport, debugging, and optional Feishu integration. Begin with the example file included in the selected release and change only values you understand.

The optional Feishu webhook is also credential-like. Prefer an environment variable over embedding its URL in application code. User-ID mappings depend on the team's Feishu environment and must be supplied by the operator rather than guessed.

Start HTTP transport and verify Lanhu MCP locally

Docker Compose starts the configured service when docker compose up -d --build succeeds. For a source installation, start the installed command explicitly with HTTP transport.

On Linux or macOS:

./venv/bin/lanhu-mcp --transport http

On Windows:

venv\Scripts\lanhu-mcp.exe --transport http

Leave a foreground source process running during testing. If it exits, read the terminal output before restarting. Check the Python version, installed dependencies, Playwright Chromium installation, cookie configuration, and port availability.

The documented local MCP URL is:

http://localhost:8000/mcp

Verify in layers

1. Confirm that the source process remains running or that Compose reports an active service.
2. Inspect startup logs for fatal configuration or dependency errors.
3. Check that the local TCP listener accepts a connection.
4. Use an MCP-compatible client to initialize the transport and discover tools.
5. Perform a narrow, read-only request against a project the configured Lanhu account is authorized to access.

Use curl only as a basic reachability check:

curl --verbose --max-time 5 http://localhost:8000/mcp

For the functional test, connect locally and allow the client to enumerate the available tools. Perform a read-only operation against a known project or requirement. Confirm that returned project, page, and design information belongs to the expected workspace. This checks more than listener health: it exercises the cookie, Lanhu account permissions, MCP transport, and tool execution.

If text retrieval works but visual interpretation does not, verify the model selected in the MCP client. Lanhu MCP can provide screenshots and design resources, but the connected model must support image understanding.

Connect Cursor, Claude Code, or another MCP client

Client configuration depends on the transport. The upstream project lists Cursor, Windsurf, Claude Code, and other MCP-capable tools as relevant clients. Its AI installation guide and English project documentation provide current project context. Client interfaces and configuration schemas can change independently, so verify the settings accepted by the installed client release.

Local stdio connection

The repository includes platform scripts that enter the project directory, read .env, and start stdio transport:

./run-stdio.sh

run-stdio.bat

In a client that supports command-and-arguments MCP definitions, select the appropriate script as the command. Use an absolute path if the client starts with a different working directory. Do not start the HTTP service merely to use stdio.

Local HTTP connection

In a client that supports HTTP MCP servers, enter the complete endpoint:

http://localhost:8000/mcp

Do not put LANHU_COOKIE in this client definition. That cookie belongs on the Lanhu MCP host and authorizes server-side access to Lanhu.

Remote HTTP credentials are client-specific

A protected remote endpoint normally requires the MCP client to present a credential to the gateway, such as through an HTTP header or another supported access flow. The evidence supplied for this guide does not establish one credential configuration that works across current Cursor, Claude Code, Windsurf, and other HTTP MCP clients. It also does not establish a tested reverse-proxy configuration for Lanhu MCP.

Therefore, this article does not provide a production-ready authentication recipe. Before remote rollout, confirm from the selected client's current documentation that it can send the exact credential required by your chosen gateway. If the client cannot send that credential during MCP initialization and subsequent requests, the gateway and client are not compatible for this deployment.

Define and test the authorization boundary before remote access

The available Lanhu MCP documentation does not establish built-in authentication or per-user authorization for its HTTP endpoint. HTTPS protects traffic in transit to the tunnel edge, but it does not identify an approved MCP user. A private URL, generated subdomain, or knowledge of the /mcp path is not access control.

Keep the two credentials separate. LANHU_COOKIE lets the server access Lanhu. A gateway credential identifies or authorizes the remote MCP client. A remote user should never receive the Lanhu browser cookie.

Required authorization tests

Run these tests against the gateway's local protected address before creating or starting a public tunnel. Use the same path and transport that the remote client will use.

Record the tested client version, gateway version, credential mechanism, protected local URL, and expected rejection behavior. Repeat both negative and positive tests after upgrades. An HTTP status alone is not enough for the positive test: the authorized client must complete MCP initialization and discover tools through the gateway.

If you cannot complete all tests, keep Lanhu MCP local. An alternative private-access architecture may be more appropriate, but standard Localtonet HTTP tunneling should not be described as a VPN or as an authorization system.

Configure a Localtonet HTTP tunnel for a protected listener

After local MCP verification and authorization testing, our client can establish an outbound connection to a Localtonet relay server. This provides public HTTP connectivity without inbound router port forwarding, a public IP address, VPN setup, or direct inbound firewall changes. The tunnel is available only while the selected Localtonet device is connected and the tunnel is running.

Follow the current Localtonet HTTP tunnel documentation when working in the dashboard. The sequence below includes the documented HTTP Process Type, device token, relay server, local target, and Start action.

Repeat the authorization tests remotely

Test from a network outside the server's local network. First connect without credentials and confirm that the gateway rejects access. Repeat with an invalid credential. Then use the chosen client's supported credential method and confirm that MCP initialization, tool discovery, and one narrow read-only operation succeed.

Finally, stop the Localtonet tunnel and confirm that the public endpoint is no longer reachable. Restart it only when remote access is required. If the unauthenticated or invalid-credential tests succeed unexpectedly, stop the tunnel immediately and correct the gateway before sharing the URL.

Routine operation, shutdown, and upgrades

Treat a shared MCP server as an application service. Monitor process state, review failures without publishing sensitive logs, keep the Lanhu cookie current, and periodically perform a small read-only verification. Also test the gateway's negative authorization cases after configuration changes.

Docker Compose operations

Inspect status and logs:

docker compose ps
docker compose logs

Stop and remove the running Compose containers:

docker compose down

After checking out an intended release and reviewing its configuration changes, Docker deployments must rebuild the image:

docker compose up -d --build

Source process operation

Stop a foreground source process from its terminal. For persistent use, apply the operating system's normal service-management mechanism while preserving the repository working directory, virtual environment, protected environment configuration, and required data-directory permissions. Do not invent additional Lanhu MCP flags beyond those documented by the selected release.

Upgrade evidence limitation

The v1.8.6 release notes define the required upgrade outcome but do not provide one complete command sequence that is valid for every source checkout, wheel installation, branch strategy, virtual environment, or service manager. They state that a normal source installation should retrieve the intended tag, upgrade dependencies, reinstall the package, and restart the MCP client. Docker users must rebuild the image.

Because repository state and installation method determine the safe Git and package commands, this guide does not invent a universal upgrade sequence. Before upgrading, stop remote access, back up required data, identify the currently installed method and version, and follow the upstream v1.8.6 upgrade instructions together with the repository's current deployment documentation. Compare the new environment examples with your local configuration without overwriting the protected cookie.

After the upgrade, restart the service using the documented command for its installation path. Expect screenshot cache schema 4 to rebuild tile metadata once when moving to v1.8.6. Repeat local tool discovery, a known read-only Lanhu request, all gateway authorization tests, and the remote tunnel shutdown test.

The release also says that an existing compatible single-file deployment can replace lanhu_mcp_server.py because the file embeds the matching lanhu_design implementation. That statement assumes compatible dependencies. A full repository, wheel, or Docker installation remains the upstream recommendation for keeping code and dependencies synchronized.

Credential lifecycle

Replace the Lanhu cookie when its browser session expires, the account loses access, or disclosure is suspected. Where organizational policy permits, use an account limited to the projects and permissions required by the MCP workflow. Removing someone from an MCP client does not revoke the server-side Lanhu cookie or a separately issued gateway credential.

Keep Localtonet device tokens private. Revoke or rotate gateway credentials when users, devices, or access requirements change. Stop tunnels that are not needed instead of leaving a protected but unused service continuously reachable.

Troubleshooting installation and connectivity

The source installer reports an unsupported Python version

Run python3 --version or python --version and confirm Python 3.10 or newer. A virtual environment retains the interpreter with which it was created. Recreate the environment using the correct interpreter if necessary.

The service cannot start on port 8000

Another process may be listening on the port. Stop the conflicting service or set SERVER_PORT to an available value. Update the local verification URL, Docker port publication where applicable, gateway upstream, MCP client URL, and Localtonet target so every layer uses the same effective port.

The local request returns connection refused

Confirm that the source command is still running or that Compose reports an active service. Review startup output for a missing cookie, package error, failed Chromium installation, or port conflict. Verify the actual bind address and port.

Docker reports a running container, but localhost does not work

Check the application logs and effective Docker port publication. The process inside the container must accept traffic on the container interface, which is why the documented 0.0.0.0 value matters. A healthy internal process is not reachable from the host unless the Compose configuration publishes the required port.

A source listener works locally but not from the Localtonet device

If our client runs on another machine, the Lanhu MCP or gateway service cannot remain bound only to the source host's loopback interface. Use an appropriate private interface and firewall policy, or run our client on the same host. Test the target directly from the Localtonet device before changing the tunnel.

The endpoint returns an HTTP error to curl

A basic request does not perform a complete MCP handshake. If curl receives an HTTP response, network reachability may be working even when the method or protocol data is rejected. Continue with a compatible MCP client and review server logs.

The client connects but cannot retrieve Lanhu data

Confirm that LANHU_COOKIE contains the current complete Cookie request-header value and that the account can access the project in the browser. Check for accidental whitespace or quoting introduced while editing. Replace an expired cookie and restart the service so it receives the new value.

Text works but screenshot analysis fails

Verify that Playwright Chromium was installed in the same virtual environment used to run Lanhu MCP. For Docker, inspect build and runtime logs. Confirm that the AI client uses a vision-capable model.

The Localtonet address cannot reach the protected service

Test the gateway's local target from the device running our client. Confirm the selected device is connected, the correct relay is selected, the target IP and port are accurate, and the tunnel was started. Creating the tunnel alone does not run it.

The gateway rejects the authorized MCP client

Confirm that the client can transmit the gateway's required credential on MCP HTTP requests, not only on an initial browser request. Check the exact client version and gateway configuration. If compatibility cannot be established, stop the tunnel and keep the service local.

The endpoint works without gateway credentials

Stop the tunnel immediately. Verify that the tunnel targets the gateway rather than port 8000 directly, that the gateway protects the /mcp path, and that anonymous access is disabled. Repeat missing, invalid, valid, and revoked credential tests before restarting remote access.

Frequently asked questions