Linux File Bridge
Provides tools for safely reading and writing files in Android shared storage directories (e.g. /sdcard, ~/storage/shared) from inside an proot/chroot Ubuntu or Termux environment, letting agents access project files that live in Android shared folders.
Provides tools for accessing file systems of Ubuntu (proot/chroot/container) environments, exposing directories as token-protected, path-safe roots with list, read, write, tree, search, upload/download, and cross-environment sync/copy operations.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Linux File Bridge · Linux 文件互通器
一个零第三方依赖的小工具,让手机端应用集成的 agent 在任意一个 Ubuntu / proot / chroot / Termux / WSL 环境里,安全地读写其他环境和 Android 共享目录中的项目文件。
典型场景:PocketDev 之类的手机端 agent 运行在 Ubuntu 20.04 proot 中,项目却散落在另一个 Ubuntu 容器、Termux 的
~/storage/shared或局域网机器上。为每个环境启动一个轻量 bridge,再用一个 MCP / HTTP 入口聚合,agent 就能用统一路径访问全部项目。
目录
Related MCP server: Rob Desktop Commander
为什么需要它
在手机上,agent 往往只能看到自己所在的那个 proot 根文件系统:
另一个 Ubuntu 环境里的项目路径不可见;
Termux 的
/sdcard/~/storage/shared没有挂载进 Ubuntu;想让 agent “读一下另一个容器里的配置” 或 “把代码同步到另一个环境”,只能手工
adb、scp或复制粘贴;手机端应用通常只支持 MCP 或 HTTP,没有现成的跨环境文件工具。
Linux File Bridge(命令名 lfb)只做一件事:把“某个环境里的某个目录”暴露成一个带 token 的、路径安全的文件 API,再把这些环境聚合成一个 agent 可用的工具面。
它不依赖 FUSE、不要求 root、不要求 systemd,也不需要安装 aiohttp/Flask 等第三方包。
特性
零第三方依赖:只使用 Python 3.8+ 标准库,能直接在 proot Ubuntu / Termux 中运行。
单环境 Bridge:
lfb serve暴露若干命名 root,支持列表、读、写、下载、上传、搜索、树、原子替换、Range 下载。多环境 Gateway:
lfb gateway用?env=或X-LFB-Env选择环境;本地环境进程内处理,远程 bridge 流式反向代理。MCP stdio 服务器:
lfb mcp直接作为手机应用的 MCP server,提供 11 个文件/命令工具,agent 无需自己发 HTTP。路径安全:拒绝
..;所有符号链接目标都必须在 root 内;逃逸链接在列表中标记blocked且不可读。Token 认证:Bearer token,常量时间比较;配置以
0600保存。读只读 root:
"mode": "ro"的 root 在服务端强制只读。默认本机监听:默认
127.0.0.1,不主动暴露公网;TLS 可选。CLI 互通:
ls/cat/get/put/sync/cp/find可在任意两个环境之间复制、镜像和校验。无守护进程依赖:前台运行,适合 Termux、proot、
termux-services或自己的启动脚本。
架构
┌────────────────────────────── Android 手机 ──────────────────────────────┐
│ │
│ ┌─────────────────────┐ MCP (stdio) ┌───────────────────┐ │
│ │ 手机端应用 / Agent │ ◄───────────────────────► │ lfb mcp │ │
│ │ (PocketDev 等) │ │ (聚合器进程) │ │
│ └─────────┬───────────┘ └─────┬────────┬────┘ │
│ │ HTTP /v1/* (可选) │ │ │
│ ▼ │ │ │
│ ┌─────────────────────┐ │ │ │
│ │ lfb gateway :8787 │ ────────────────────────────────┘ │ │
│ └─────────┬───────────┘ 本地环境直接读写 │ │
│ │ 反向代理 + 流式转发 │ │
│ ▼ ▼ │
│ ┌─────────────────────┐ HTTP ┌───────────────────────────┐ │
│ │ Ubuntu A (本环境) │ ◄─────────────── │ lfb bridge :8790 │ │
│ │ /workspace/linux │ │ root: project=/workspace │ │
│ └─────────────────────┘ └───────────────────────────┘ │
│ │
│ ┌─────────────────────┐ HTTP ┌───────────────────────────┐ │
│ │ Ubuntu B (另一容器) │ ◄─────────────── │ lfb bridge :8791 │ │
│ │ /workspace/other │ │ root: project=/workspace │ │
│ └─────────────────────┘ └───────────────────────────┘ │
│ │
│ ┌─────────────────────┐ HTTP ┌───────────────────────────┐ │
│ │ Termux │ ◄─────────────── │ lfb bridge :8792 │ │
│ │ ~/storage/shared │ │ root: shared=... (ro) │ │
│ └─────────────────────┘ └───────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘Android 上多个 proot 容器通常共享网络命名空间,
127.0.0.1:<port>可互通;如果不行,改用设备局域网 IP,并务必配合 token/TLS。一个进程可以同时是“本地环境 + 聚合器”:例如在 Ubuntu A 的配置里,
ubuntu-a是 local,ubuntu-b是 bridge;lfb mcp会同时访问两者,无需先启动 gateway。Gateway 不是必需的;它只是给“只支持 HTTP 工具”的应用一个统一入口。
快速开始(Android + Ubuntu proot)
以下命令在项目根目录执行(示例路径为 /workspace/linux,请按实际路径替换)。
1. 安装
# Ubuntu 20.04 proot
sudo apt-get update && sudo apt-get install -y python3 python3-pip
# 从源码安装(推荐开发/手机场景)
python3 -m pip install --user -e .
export PATH="$HOME/.local/bin:$PATH"
lfb --version不想安装也可以直接运行:
python3 -m lfb --help。下面的lfb均可替换为python3 -m lfb。
2. 为当前环境建配置
lfb init --name ubuntu-main --root project=/workspace/linux
# 输出 config 路径、root、gateway 端口和下一步提示
lfb env token ubuntu-main # 打印这个环境的 bearer token默认配置在 ~/.config/lfb/config.json(可用 LFB_CONFIG 或 --config 覆盖),权限为 0600。
3. 启动当前环境的 bridge
lfb serve --env ubuntu-main
# lfb bridge 'ubuntu-main' listening on http://127.0.0.1:8790验证:
TOKEN=$(lfb env token ubuntu-main)
curl -s -H "Authorization: Bearer $TOKEN" \
'http://127.0.0.1:8790/v1/list?root=project&path='4. 在另一个 Ubuntu 环境里启动第二个 bridge
进入另一个 proot / 终端,安装同一份代码后:
lfb init --name ubuntu-dev --root project=/workspace/other --gateway-port 8788
# 修改配置中的 serve.port,或启动时显式指定:
lfb serve --env ubuntu-dev --port 8791
lfb env token ubuntu-dev5. 在 agent 所在环境聚合
回到 ubuntu-main,把 ubuntu-dev 加成一个 bridge 环境:
lfb env add ubuntu-dev \
--url http://127.0.0.1:8791 \
--token '<ubuntu-dev 的 token>'
lfb env list
lfb ls ubuntu-dev:project现在 lfb 已经可以跨环境操作了。把它接到 agent:
lfb mcp把 examples/mcp.json 合并进手机应用的 MCP 配置即可(把 command 改成 lfb 的绝对路径,args 中的配置路径改成绝对路径)。应用中的 agent 会看到 lfb_list_envs、lfb_read、lfb_write 等工具。
三种使用方式
1. MCP:给应用内 agent 用
启动(应用会替你启动,通常不需要手动运行):
lfb mcp应用配置示例(command 用 which lfb 的绝对路径):
{
"mcpServers": {
"linux-file-bridge": {
"command": "/usr/local/bin/lfb",
"args": ["--config", "/root/.config/lfb/config.json", "mcp"]
}
}
}如果 lfb 不在 PATH 中,可用:
{
"mcpServers": {
"linux-file-bridge": {
"command": "/usr/bin/python3",
"args": ["-m", "lfb", "--config", "/root/.config/lfb/config.json", "mcp"]
}
}
}MCP 协议细节见 docs/API.md。服务器只把 JSON-RPC 写到 stdout,日志全部走 stderr。
2. HTTP Gateway:给 HTTP 工具用
lfb gateway # 默认 127.0.0.1:8787聚合后的 API 与单环境 bridge 完全一致,只是多一个环境选择器:
TOKEN=$(python3 -c 'import json; print(json.load(open("/root/.config/lfb/config.json"))["gateway"]["token"])')
curl -s -H "Authorization: Bearer $TOKEN" \
'http://127.0.0.1:8787/v1/list?env=ubuntu-dev&root=project&path='
curl -s -H "Authorization: Bearer $TOKEN" \
-H 'X-LFB-Env: ubuntu-dev' \
'http://127.0.0.1:8787/v1/read?root=project&path=README.md'lfb gateway 对 local 环境直接处理,对 bridge 环境做流式反向代理(上传/下载不会整体读进内存)。
3. CLI:同步和日常操作
lfb ls ubuntu-dev:project
lfb cat ubuntu-dev:project/README.md
lfb find ubuntu-dev:project --glob '*.py' --max 50
lfb get ubuntu-dev:project/src ./src -r
lfb put ./dist ubuntu-main:project/dist -r
lfb sync ubuntu-main:project ubuntu-dev:project --dry-run
lfb sync ubuntu-main:project ubuntu-dev:project --delete --allow-root-delete路径语法:
env:root/path
env:root # root 本身
root/path # 默认环境 + 指定 root
path # 默认环境 + 默认 rootsync 是“把源目录内容镜像到目标目录”;--delete 会删除目标中多余的文件。目标为 root 本身时,--delete 必须额外加 --allow-root-delete,这是防止误删的保护。
多环境拓扑示例
方案 A:一个配置包含所有环境(推荐)
在 agent 所在环境维护一份配置:
lfb init --name ubuntu-main --root project=/workspace/linux
lfb env add ubuntu-dev --url http://127.0.0.1:8791 --token '...'
lfb env add termux-shared --root shared=$HOME/storage/shared --read-only
lfb mcpubuntu-main 和 termux-shared 由 lfb 直接读写;ubuntu-dev 通过 HTTP bridge。agent 只需连接一个 MCP 进程。
方案 B:每个环境独立配置 + Gateway
每个 Ubuntu 环境各自 lfb init 并 lfb serve;在手机某个环境里维护聚合配置并 lfb gateway。适合每个容器由不同人/脚本管理,或者应用只支持 HTTP 的场景。
方案 C:临时跨环境复制
不启动常驻服务,只在一台机器上运行 CLI:
lfb sync /path/a user@phone:/path/b # 不支持 ssh 语法,请用下面的方式
lfb sync ubuntu-main:project ubuntu-dev:project跨机器请用桥接环境(lfb env add remote --url ...),或先用 get/put 走现有 SSH/rsync。
MCP 工具
工具 | 作用 | 关键参数 |
| 列出环境、root、只读/exec 状态 | — |
| 列目录; |
|
| 嵌套目录树 |
|
| 元数据、可选 SHA-256 |
|
| 读 UTF-8 文本(偏移/上限) |
|
| 原子写文件;parent 自动创建 |
|
| 建目录 |
|
| 同环境移动/改名 |
|
| 删除文件/目录 |
|
| glob/regex/内容搜索 |
|
| 执行命令(默认关闭) |
|
所有工具都支持 env、root;path 也可以写成 env:root/path。二进制文件请用 HTTP /v1/download 或 CLI lfb get。
CLI 速查
lfb init 创建配置
lfb env 管理环境(list/add/remove/default/show/token)
lfb serve 单环境 HTTP bridge
lfb gateway 多环境聚合 HTTP 入口
lfb mcp 给应用 agent 的 MCP stdio 服务器
lfb health 检查环境连通性
lfb roots 列出 root
lfb ls/tree/stat/cat/find
lfb get/put 下载/上传(支持 -r)
lfb mkdir/mv/rm
lfb sync|cp 跨环境复制/镜像(--delete/--dry-run/--checksum)
lfb exec 执行命令(需配置开启)
lfb doctor 配置、权限、连通性诊断lfb exec 的选项要放在 target 之前,命令放在 target 之后:
lfb exec --env ubuntu-main --shell project 'git status --short'
lfb exec --env ubuntu-main project -- git status --short
lfb exec --env ubuntu-main --timeout 10 project -- ls -la--shell 需要配置里 exec.allow_shell=true;exec 整个功能需要 exec.enabled=true。默认关闭。
HTTP API
所有响应使用统一信封:
{"ok": true, "data": { ... }}
{"ok": false, "error": {"code": "not_found", "message": "path not found: ..."}}认证:Authorization: Bearer <token>(也支持 X-LFB-Token)。/v1/health 不需要认证。
方法 | 路径 | 说明 |
GET |
| 健康检查(无需认证) |
GET |
| 列出 root、limits、exec 状态 |
GET |
| 目录列表 |
GET |
| 文件元数据 |
GET |
| 读文本(二进制需 |
GET |
| 原始下载,支持 |
PUT |
| 原始上传(必须带 |
POST |
| JSON |
POST |
| JSON |
POST/DELETE |
| 删除 |
GET |
| 搜索 |
GET |
| 目录树 |
POST |
| JSON `{root,path,argv |
GET |
| 仅 gateway:列出所有环境 |
Gateway 额外支持 ?env=NAME 和 X-LFB-Env: NAME;响应会回显 X-LFB-Env。
完整字段和示例见 docs/API.md。
配置文件
默认路径:~/.config/lfb/config.json($LFB_CONFIG 可覆盖)。最小示例:
{
"version": 1,
"default_env": "ubuntu-main",
"environments": {
"ubuntu-main": {
"kind": "local",
"roots": {
"project": {"path": "/workspace/linux", "mode": "rw"},
"shared": {"path": "/root/storage/shared", "mode": "ro"}
},
"token": "请替换为随机 token",
"serve": {"host": "127.0.0.1", "port": 8790},
"limits": {"max_read": "1M", "max_upload": "512M", "max_search_results": 200},
"exec": {"enabled": false, "allow_shell": false}
},
"ubuntu-dev": {
"kind": "bridge",
"url": "http://127.0.0.1:8791",
"token": "另一个环境的 token",
"timeout": 30
}
},
"gateway": {
"host": "127.0.0.1",
"port": 8787,
"token": "gateway token",
"default_env": "ubuntu-main"
}
}kind:local(直接读写本机)或bridge(HTTP 客户端)。roots: 命名 root;mode为rw或ro;agent 只能看到这些目录。read_only: 环境级只读,等价于所有 root 只读。limits: 单次读取上限、上传上限、搜索上限;支持1M/512M写法。exec: 默认关闭;开启后以当前用户身份运行,不是沙箱。serve: 该环境lfb serve的默认 host/port,可选tls_cert/tls_key。gateway: 聚合器监听地址和 token;gateway.token为空时回退到默认环境的 token。verify_tls: bridge 默认校验;自签证书测试时可设false(不推荐),或用--ca。
用 lfb doctor 检查文件权限、root 是否存在、bridge 是否可达、token 是否缺失。
安全模型
请把它当成“带 token 的文件 API”,而不是 SSH 的替代品。
默认只监听 127.0.0.1。需要跨设备时显式
--host 0.0.0.0,并务必使用 TLS + 强 token + 防火墙/VPN。所有 root 之外的路径都拒绝:
..直接报错;符号链接解析后必须在 root 内;逃逸链接在列表里显示为blocked,且不可读、不可写。Token 常量时间比较;配置文件写入
0600,所在目录0700。不要把配置提交到 Git。原子写:先写同目录临时文件、
fsync、rename;不会出现半截文件。只读 root 由服务端强制,不是客户端的君子协定。
exec 默认关闭;开启后命令以运行
lfb的用户身份执行,没有容器隔离、没有 seccomp。不要对不可信客户端开放。没有速率限制、没有多用户 ACL。一个 token 等于该环境全部 root 的权限。需要多用户请每个用户单独跑一个 bridge/端口/token。
HTTPS 使用标准库
ssl;证书和私钥路径在配置或命令行传入。自签证书需让客户端信任对应 CA。
更完整的威胁模型和部署建议见 docs/SECURITY.md。
Android / proot / Termux 注意事项
proot 没有 systemd:用
nohup、termux-services或 Termux:Boot 启动lfb serve;前台运行时日志在 stderr。端口:不同 proot 进程共享 Android 网络栈,通常可
127.0.0.1:8790/8791互通。绑定失败时先lfb doctor或换端口。/sdcard 权限:Android 11+ 对共享存储有限制;Termux 里先
termux-setup-storage,再把~/storage/shared配置成 root。Ubuntu proot 不一定能看到该路径,按实际挂载点配置。PATH:
pip install --user后~/.local/bin可能不在 PATH;用绝对路径或在应用 MCP 配置里写全路径。Python 版本:需要 3.8+;Ubuntu 20.04 自带的 3.8 足够。代码没有使用 3.9+ 语法。
不要用
pgrep -f匹配自身命令来杀进程:本项目的文档和脚本不使用这种方式;停止前台服务用 Ctrl-C,后台服务请记录 PID 或用termux-services。电池/休眠:Android 可能冻结后台进程;需要常驻时给 Termux/应用加电池白名单。
后台启动示例:
scripts/start-bridge.sh ubuntu-main用nohup启动并把 PID 写入~/.lfb/run/;scripts/stop-bridge.sh ubuntu-main只按 PID 文件停止,不会用pgrep搜索命令行,因此不会误杀当前终端。跨多个 proot 环境时,在每个环境分别运行。
开发与测试
git clone https://github.com/wangzi5151/linux-file-bridge.git
cd linux-file-bridge
python3 -m pip install -e .
make test # 等价于 python3 -m unittest discover -v测试覆盖:配置校验、路径穿越、符号链接逃逸、只读 root、原子读写、mtime 保留、Range 下载、HTTP 认证、Gateway 本地/代理、MCP 协议与工具、CLI、跨环境 sync/delete。
GitHub Actions 已启用,配置见 .github/workflows/ci.yml:在 Python 3.8 / 3.9 / 3.10 / 3.11 / 3.12 / 3.13 上跑完整测试、CLI 冒烟、wheel/sdist 构建与干净虚拟环境安装,并启动真实 bridge 走一遍 health → list → lfb ls → lfb cat 的端到端冒烟。Fork 项目时可直接沿用;examples/github-actions-ci.yml 保留为精简模板。
目录结构:
lfb/
api.py HTTP 处理器和单环境 server
backends.py local/bridge 统一后端
cli.py 命令行
client.py 流式 HTTP 客户端
config.py 配置模型
errors.py 错误码
fsops.py 安全文件系统操作
gateway.py 多环境反向代理
mcp.py MCP stdio 服务器
targets.py env:root/path 解析
transfer.py 传输、镜像、删除
util.py
tests/
examples/
docs/欢迎 issue / PR。提交前请跑 make test,并保持零运行时依赖。
限制与路线图
当前版本(0.1.0)有意保持小:
不是 FUSE 挂载,没有内核级“把远程目录挂到本地”的能力;agent 通过工具/CLI 访问。
没有文件锁、冲突检测或版本历史;并发写以“最后写入者获胜”为准。
上传要求
Content-Length,不支持 chunked 请求体(本项目客户端始终发送长度)。单个文本读取有上限(默认 1 MiB,MCP 默认 256 KiB);大文件请分段或下载。
逃逸 root 的符号链接无法通过
rm删除(安全优先);需要时在宿主机处理。sync跳过符号链接;不保留目录 mtime/ACL/xattr。仅支持 Bearer token;没有 OAuth、ACL、审计日志。
可能的后续方向:可选的 audit log、文件锁/ETag 条件写、rsync 风格增量、MCP resources、HTTP MCP transport、Web UI。
English
Linux File Bridge (lfb) is a tiny, dependency-free Python tool that lets an agent inside one Android Linux environment (Ubuntu proot/chroot, Termux, WSL) read and write project files in other environments and Android shared storage.
Run
lfb servein each environment to expose named, path-confined roots over an authenticated HTTP API.Run
lfb gatewayto aggregate local and remote environments behind one endpoint (?env=/X-LFB-Env).Run
lfb mcpto expose 11 file tools to a mobile app over MCP stdio.Use
lfb sync/lfb cpfor cross-environment mirroring,lfb get/putfor transfers.
Security defaults: loopback bind, bearer auth, config 0600, .. and symlink-escape protection, read-only roots enforced server-side, command execution disabled.
Quick start:
python3 -m pip install --user -e .
lfb init --name ubuntu-main --root project="$PWD"
lfb serve --env ubuntu-main
# another terminal/app:
lfb mcpDocs: API · Security · Architecture.
License
MIT. See LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Browse and manage files in your Moxt AI workspace from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceGives MCP-compatible AI clients a controlled bridge to local files, processes, search, and document utilities, including reading/writing and moving files, text block editing, directory listing, content search, starting and managing terminal processes, and PDF/Excel/DOCX/image handling. It serves these tools over MCP Streamable HTTP at a configurable endpoint, with optional Bearer-token authentication and read-only or restricted-directory modes for safer remote exposure.1MIT
- AlicenseAqualityBmaintenanceEnables MCP-capable AI clients to control a local computer over stdio with filesystem operations, ripgrep search, shell command execution, and persistent process sessions.14MIT
- AlicenseNot gradedqualityBmaintenanceExposes a single SSH-reachable host as MCP tools for running and backgrounding remote commands, resumable verified file transfers, and read-only file comparison, stat, hashing, listing and reading. Runs on loopback with per-request Bearer auth and hot-switchable permission levels, letting an agent compile and manage files on a build machine while keeping its workspace on the device.MIT
- AlicenseNot gradedqualityBmaintenanceExposes filesystem operations (read, write, list, move, delete, search), shell command execution, screenshots, mouse and keyboard control, and screen/window inspection as 15 tools plus configuration resources over stdio, SSE, or streamable HTTP. It lets MCP clients drive local computer-use and file management tasks with a fully local model stack.MIT