Lan Direct
io.github.farshadmomo由 GitHub 账号 farshadmomo 发布v1.0.2更新于 Oct 24, 2026
Browser MCP: the app under test egresses via the real ISP while the agent stays on the VPN.
概览
一个本地浏览器 MCP 与技能，让编码代理通过真实 ISP 访问本地站点，而代理自身仍留在全隧道 VPN 上。
- 可以做什么
- 通过 Playwright 浏览器服务器浏览网页，并按主机逐条连接分流：列表中的本地主机走物理 ISP 网卡，其余走 VPN 隧道，同一会话内完成。用路由查询命令查看某主机将走哪条线路，规则来自合并后的列表。在用户文件中添加自己的主机规则，该文件不受更新影响。配合随附技能检测并验证绕过是否生效，通过预加载为 Node 后端绑定套接字，或为其他技术栈运行本地代理。
- 适用场景
- 当代理必须保持 VPN 开启才能访问其 API，而被测应用或网站拒绝 VPN 的境外出口 IP 时使用，例如本地 API、支付或短信网关、银行接口。适用于需要同时使用两种网络的测试与浏览场景。
- 运行要求
- 需要 Node 20.6 或更高版本，Windows 上还需 PowerShell，Linux/macOS 上需 bash 和 curl。可从 npm 或 git 克隆安装，并注册为本地 stdio 服务器；之后需重启代理。绕过生效需要可用的全隧道 VPN 和物理网络适配器。
安装
在 SourceWeft 中
- 打开 控制台中的 Lan Direct，将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
lan-direct
A skill and a browser MCP for coding agents behind a full-tunnel VPN — Claude Code and Codex.
Your VPN has to stay on, because that's how the agent reaches its API. But the app you're testing calls services that reject the VPN's foreign exit IP: a domestic API, a payment or SMS gateway, a bank endpoint. Turning the VPN off isn't an option — it cuts the agent off.
lan-direct gives the app an ISP-direct path while the agent stays on the tunnel. No admin, no routing-table edits, no VPN reconfiguration. How it works.
Install
Requires Node ≥ 20.6, plus PowerShell on Windows or bash and curl on Linux/macOS. No
admin, no symlinks, no renaming.
From npm
Then restart the agent. That's it — the same three lines on every platform.
npx -y lan-direct browser is the better MCP command however you install: it survives the
checkout moving, which an absolute path into a clone does not.
Why
"--"is quoted. On Windowsclauderesolves toclaude.ps1, and PowerShell's parameter binder strips a bare--before the script ever sees it. The CLI then reads-yas one of its own flags and fails witherror: unknown option '-y'. Quoting protects it, and quotes are a no-op in bash — so the same line works in PowerShell, bash and cmd.
From a clone
Prefer this if you want to edit the skill or track it — one git pull updates everything,
where npm needs npm update -g lan-direct && lan-direct install-skill because install-skill
copies files rather than linking them.
Either way, your own host list at ~/.lan-direct-hosts is never touched.
1. Clone into your agent's skills directory. Both agents discover skills by scanning a
directory for SKILL.md — they just scan different ones.
2. Register the browser MCP:
The installer verifies the bypass actually works, registers the server against this checkout,
and prints the equivalent ~/.codex/config.toml block for Codex. Safe to re-run — it replaces
the existing entry rather than duplicating it.
On Linux/macOS there's no installer script; register it directly:
Restart the agent. Then /lan-direct in Claude Code, or in either agent just describe the
problem — the description frontmatter is the trigger, firing on phrasings like "test this
while my VPN is on" or "the API rejects the VPN IP".
To update: git -C <that directory> pull. No reinstall needed.
Using both agents from a single clone
Clone once, then link the second location. On Windows a junction works without admin or Developer Mode, unlike a symlink:
macOS/Linux:
One git pull then updates both.
Installing somewhere else (for editing the skill)
Clone wherever you like and link it in. A junction needs no admin; a symlink needs an elevated shell or Developer Mode:
However you install it, the directory inside the skills folder must be named lan-direct
— both agents discover by directory name, and it has to match name: in SKILL.md.
Which hosts go via the ISP
Rules live in lan-hosts.txt and are suffix matches:
Anything not matched takes the tunnel. List domestic hosts only — adding a foreign one sends it out through an ISP that may filter it.
The shipped list covers .ir wholesale plus the Iranian services that live on other TLDs:
payment (zarinpal, payping, nextpay), SMS/OTP (kavenegar, melipayamak, farazsms, ippanel),
hosting (parspack, hostiran, mizbanfa), maps (neshan), commerce (digikala, torob, basalam),
education and jobs (quera, faradars, maktabkhooneh, 7learn, irantalent), AI (hoosha, gapgpt),
and the analytics domains those sites embed (najva, yektanet). Every one was checked: all are
unreachable over the tunnel and respond over the ISP.
Adding your own
Put them in ~/.lan-direct-hosts, one per line, same format:
That file is never touched by git pull, and is read each time the browser starts — no
reinstall, no restart of anything but the browser. Rules from all three sources merge:
shipped file, your file, and any --lan-hosts a,b passed at launch.
Getting a rule wrong fails in a way that looks like the site being down, so the proxy prints the route it chose for every connection. Check that before blaming the site — or ask directly, without starting anything:
What's in the box
Two halves, installed together:
The MCP is what makes browsing work at all — Chromium has no source-binding flag, so a browser can only reach the ISP through a proxy. Without it the skill covers backends and CLIs but not pages.
How it works
Per-socket source-address binding. A socket explicitly bound to the physical adapter's IP takes that adapter's default route instead of the tunnel's:
No admin rights, no routing-table edits, no VPN reconfiguration, nothing global. Because it's per-socket it is opt-in by construction — a process that doesn't ask for it cannot be affected. That's the property that keeps the agent on the tunnel.
This is deliberately not route add. A static route is global: it would pull every process
off the tunnel for that destination, the agent included, and it needs admin.
A server process has no --interface flag, so there are two ways to give it one:
The Node trap
If your backend is Node, HTTP_PROXY will not work and will fail silently.
Native fetch runs on Node's built-in undici, which ignores proxy environment variables on
Node ≤ 23 and accepts no https.Agent. Verified on Node 22.20: plain env vars,
NODE_USE_ENV_PROXY=1, and --use-env-proxy all do nothing — the proxy log stays empty while
traffic goes out over the VPN. This hits Next.js, the openai SDK, and anything else on
native fetch.
lan-bind.mjs patches net/tls in a preload, which reaches the bundled undici. That covers
native fetch, the openai SDK, axios, node-fetch, got and plain http/https at once — no
dependency, no proxy process, no HTTP_PROXY. NODE_OPTIONS propagates to forked workers, so
it covers Next.js and Vite dev servers.
It skips loopback destinations on purpose: a socket sourced from the LAN IP cannot reach
127.0.0.1, so without that guard any app with a local Redis/Postgres/Mongo would die on
EADDRNOTAVAIL.
Manual use
All paths below use $skill for wherever you installed it:
1. Detect and verify. Exits 0 only if the bypass actually works.
Emits lanIp, gateway, lanDns, subnet, tunnelActive, vpnAdapter, directEgress,
lanEgress, fakeIpDns, bypassWorks. It probes twice and compares, rather than assuming —
and refuses to proceed if the bypass doesn't hold, so you never get a false pass.
2a. Node backend. Copy-paste as-is; only lanIp needs filling in:
Same thing from Git Bash, with the path written out:
--import needs an absolute file:// URL with forward slashes on Windows — a bare Windows
path fails.
2b. Anything else. Start the proxy:
Then launch the backend with HTTP_PROXY=http://127.0.0.1:8899,
HTTPS_PROXY=http://127.0.0.1:8899, NO_PROXY=localhost,127.0.0.1,<subnet>.
See SKILL.md for stacks where HTTP_PROXY still isn't enough — notably PHP under Apache,
where the service doesn't inherit your shell and libcurl never sees the variables.
Browsing both worlds at once
Neither path is a superset of the other. Measured on an Iranian ISP behind a foreign tunnel:
That last row is why the agent must never be moved off the tunnel — do it and the agent stops working entirely.
The browser MCP handles the mix in one session. Chrome is told to send everything to the
proxy and makes no routing decision itself; the proxy reads the hostname out of each CONNECT
(visible in plaintext, before TLS) and decides:
There is no "use the VPN" code path. Binding is the only action taken — skip it and the OS routing table applies, which the tunnel owns. LAN is opt-in; the tunnel is what happens otherwise.
It is per connection, not per session. Two fetch calls from the same page can take
different physical routes — measured, on one page in one tab:
Every proxy log line names the route it chose:
The browser's proxy runs on 8900, deliberately not the 8899 used for backend testing above. The MCP reuses whatever is already listening on its port, so sharing the number would let a bind-everything backend proxy silently capture the browser and push all of its traffic through the ISP — breaking exactly the sites the tunnel exists for.
Contents
Requires Node ≥ 20.6 and curl (built into Windows 10+, standard elsewhere). No dependencies.
Development
34 tests. The routing predicate gets the most attention because it's the only logic here
whose failure is silent — a wrong match sends traffic out the wrong physical network with no
error and no log line. Both mutations it exists to catch are verified to fail the suite: a
naive endsWith (so evilhoosha.com matches hoosha.com) and a missing loopback guard.
The preload is tested in a real child process with LAN_BIND set to 192.0.2.1 — an address
the machine can't own, so a bound socket fails instantly. That's what proves the patch is
active rather than quietly doing nothing.
What CI can't cover: lan-proxy.mjs --self-test, which needs a live tunnel and a physical
adapter. Run it by hand with the VPN up. Changes are listed in CHANGELOG.md.
One gotcha if you're on an old runtime: Node 20.6.0 can't run the suite — every assertion passes and then the test runner never exits. That's a bug in that release's runner, not in lan-direct, which runs fine on it. Any current 20.x or 22 is fine.
Notes
- The proxy listens on
127.0.0.1only. Binding wider would publish an open proxy to the LAN. lan-direct route <host>shows which network a host would leave by, using your merged rule list. Faster than starting the browser to find out.- The
.ps1files are deliberately pure ASCII: Windows PowerShell 5.1 reads BOM-less UTF-8 as ANSI, and a stray em dash breaks the parser. CI enforces this. - Under fake-IP DNS (sing-box, clash), pass
--dns <lanDns>.dns.setServers()doesn't affectdns.lookup(), which goes through the OS resolver the tunnel owns. pkill -f lan-proxyfrom Git Bash does not kill a Windowsnode.exe. Use the PowerShell teardown inSKILL.md.
Verified against
nekoray / sing-box TUN on Windows 11, Node 22.20, Intel Wi-Fi — tested end to end on a real Next.js 16 app calling Neshan (Iranian maps) and AvalAI (LLM gateway), both of which reject foreign IPs outright:
The browser MCP was tested the same way: a domestic AI platform and YouTube opened
back to back in one session, the domestic site's own CDN reporting the ISP address and
country IR while YouTube rendered its German-locale shell over the tunnel.
The agent's own connection stayed on the tunnel throughout.
Adapter discovery is generic — Get-NetAdapter -Physical on Windows, a sysfs device symlink
on Linux, networksetup on macOS — so WireGuard, OpenVPN, WARP and similar should work. But
lan-detect verifies empirically rather than assuming, and exits non-zero when it can't.
Platform status. Windows is the tested path, end to end. lan-detect.sh has been run on
Linux (Ubuntu 24.04) and returns the correct interface, gateway, DNS, routes and exit codes —
but on a machine with no tunnel of its own, so the bypass-verified branch is unproven there.
macOS is written from the documented behaviour of networksetup/ipconfig/netstat and has
not been run at all. Both refuse rather than guess, so the failure mode is a clear error, not
silent VPN traffic. Reports welcome.
One caveat specific to Linux: a bound source address does not by itself override the routing
table the way it does on Windows, so a tunnel using policy routing may keep the traffic even
when bound. That is exactly what the two probes detect — if it happens, lan-detect.sh says so
and names the fix instead of reporting success.
Also unproven: lan-detect's "kill-switch detected" branch, which needs the VPN in a state the
test machine couldn't produce.
License
MIT — see LICENSE.
来源：README.md，提交 9cf0d2b
工具
0版本历史
1- v1.0.2最新Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分