termux-mcp-remote
Supports running the device agent in Termux on Android, exposing the Android device's shell, files, interactive PTY sessions, and background jobs remotely, with handling for Android kernel restrictions in system information.
Supports Debian hosts as agent devices, exposing remote shell commands, file management, interactive PTYs, background jobs, and system information; can be run as a systemd service.
Turns a Linux machine's terminal into a remotely controlled device, providing tools for shell commands, file operations, interactive PTYs, background long-running jobs, system information, and multi-device routing.
Supports Ubuntu hosts as agent devices, exposing remote shell commands, file management, interactive PTYs, background jobs, and system information; can be run as a systemd service.
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.
termux-mcp-remote
把一台 Linux 机器的终端,变成你一个人专用的远程 MCP 服务。
AI 客户端 (Claude / ChatGPT / Cursor / 任意 MCP 客户端)
│ https://mcp.你的域名/mcp
│ 请求头: Authorization: Bearer <AUTH_TOKEN>
▼
Cloudflare Worker(MCP 服务 + 鉴权 + 隧道 + WebUI)
│ WebSocket(设备主动连出去,穿过 NAT)
▼
Agent(Termux / Debian / Ubuntu / 树莓派 / 任意 Linux)
└─ shell / 文件 / 交互式 PTY / 后台长任务设备不需要公网 IP、不需要开端口、不需要 cloudflared / frp。 它主动往 Worker 建一条 WebSocket,外面的 MCP 请求由 Worker 顺着这条连接转进来。
一个 Worker 可以同时接多台设备,MCP 调用时用
device参数指定目标。
1. 安装
一行命令(推荐)
curl -fsSL https://cdn.jsdelivr.net/gh/hahahaoha/termux-mcp-remote@main/get.sh | bash国内网络如果 jsDelivr 慢,可以换源:
# GitHub 直连
curl -fsSL https://raw.githubusercontent.com/hahahaoha/termux-mcp-remote/main/get.sh | bash
# 走代理
curl -fsSL https://ghproxy.net/https://raw.githubusercontent.com/hahahaoha/termux-mcp-remote/main/get.sh | bash脚本会依次尝试 codeload → ghproxy → ghfast → github 下载代码包,任何一个通就行。
Node.js 缺失时在 Termux 上会自动 pkg install nodejs-lts(Linux 会提示安装方法)。
常用参数:
# 装到指定目录
bash get.sh --dir /opt/termux-mcp-remote
# 更新现有安装
bash get.sh --dir ~/termux-mcp-remote
# 跳过 npm install(依赖已装好)
bash get.sh --no-deps
# 确认要覆盖另一个位置的 tmcp 命令
bash get.sh --dir /opt/new --force安全保护:如果检测到已有另一个位置的安装,脚本会中止并且不改动任何文件, 而不是悄悄覆盖你的
tmcp命令。
手动安装
git clone https://github.com/hahahaoha/termux-mcp-remote.git
cd termux-mcp-remote
npm install
bash install.sh # 安装 tmcp 命令需要 Node.js >= 20。
Termux:pkg install -y nodejs-lts util-linux
Debian/Ubuntu:sudo apt install -y nodejs npm util-linux
util-linux 提供 script 命令,交互式 PTY 需要它;不装则只有 shell_* 工具不可用。
Related MCP server: Remote MCP Hub
2. 首次部署(只做一次)
tmcp deploy依次完成:
检查
wrangler登录状态(没有则提示wrangler login)生成
AUTH_TOKEN/AGENT_TOKEN,写入 Worker Secrets部署 Worker(含 Durable Object)
把地址和 token 存到
~/.config/termux-mcp-remote/config.json(600)
给新设备一键配置(配置码)
再也不用抄地址和密钥了。在后台 https://<worker>/admin → 「配置码」→ 生成,
然后在设备上:
tmcp enroll # 交互式,直接粘贴那串码
tmcp enroll <注册码> # 码里带了地址时
tmcp enroll <地址> <注册码> # 地址和码分开给一条命令把 workerUrl / AUTH_TOKEN / AGENT_TOKEN 全部写好。
tmcp setup 的第一个问题也会问注册码,粘进去就完事。
它为什么安全:
属性 | 实现 |
码里不含密钥 | 只有 Worker 地址 + 32 字节随机数;密钥在兑换那一刻才由 Worker 现取注入 |
服务端不存明文 | Durable Object 里存的是码的 SHA-256 哈希,拿到存储快照也还原不出码 |
一次性 | 兑换成功即标记 |
有时效 | 默认 10 分钟(可选 5 分钟 ~ 1 小时),过期记录直接删除 |
过期不可复原 | 记录被删 + 码本身不含密钥,过了有效期就是一串无用字符 |
可撤销 | 后台可随时撤销单个码;同时最多 20 个有效码 |
轮换友好 | 因为密钥是兑换时现取的,轮换 AUTH_TOKEN 后旧码兑换出来的也是新值 |
码长得像乱码(例如
m9_7uxtsDdGbc_PyMiTu9Ut0…),是 base64url 编码的随机数。 只显示一次,页面刷新后就看不到了——需要就重新生成。
如果 *.workers.dev 访问不了
国内网络下 *.workers.dev 常被 DNS 污染。绑自有域名:
tmcp domain列出你账号下的域名 → 选一个 → 填子域(如 mcp.example.com)→ 自动创建 Workers 自定义域
并签发证书 → 顺手把本地 workerUrl 改过去。
也可以 Dashboard 手动:Worker → Settings → Domains & Routes → Add custom domain。
3. 启动
tmcp start # 守护进程 + 崩溃自动重启
tmcp status # 本地进程 / Worker / 各设备状态
tmcp test # 4 步自检各系统后台常驻方式不同:
平台 | 常驻方式 |
Termux |
|
systemd |
|
其他 | nohup / supervisor / pm2 / Docker 随意 |
4. 接进 AI 客户端
{
"mcpServers": {
"termux": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer <AUTH_TOKEN>"
}
}
}
}tmcp deploy / tmcp token 会打印这段配置。
鉴权就是那个请求头。 没有正确的 Authorization: Bearer <AUTH_TOKEN>,/mcp 一律 401。
不支持自定义 header 的客户端可以用 X-Mcp-Token: <token>。
可选:OAuth(网页版客户端用)
Claude 网页版、ChatGPT 连接器、MCP Inspector 会自动走 OAuth。给 Worker 加一个只有你知道的密码:
cd worker && wrangler secret put OWNER_PASSWORD客户端会自动发现 /.well-known/oauth-protected-resource → 跳 /authorize 输密码 → 拿到
30 天令牌(PKCE + refresh token)。不设这个 secret 时 OAuth 端点完全不存在。
验证:node scripts/oauth-test.mjs https://你的域名 <密码>。
不需要了就 wrangler secret delete OWNER_PASSWORD。
5. WebUI(Worker 上,随时可访问)
https://<你的-worker>/admin用独立的后台密码登录,不是 AUTH_TOKEN。第一次打开会引导你设置一个(至少 8 位); 之后用这个密码登录,会话存在 HttpOnly cookie 里(7 天有效)。
tmcp admin-pass # 设置 / 重置后台密码(忘了密码时用这个)
tmcp admin-pass # 输入留空 = 清除密码,下次访问重新引导密码在服务端只存 PBKDF2-SHA256 哈希(10 万次迭代,Cloudflare 上限),
连续 8 次输错锁定 10 分钟。它和 AI 客户端用的 AUTH_TOKEN 完全无关:
拿后台密码调 /mcp 会被拒,拿 AUTH_TOKEN 也进不了后台。
登录后可以:
看设备列表:在线状态、系统/发行版/架构、版本、最后活跃时间
设备详情:进程 pid、内存、PTY 会话数、后台任务数、连接时长、磁盘
看日志:agent.log / supervisor.log / agent.err.log,可选行数
强制重连:某台设备连接卡住时
改默认设备:MCP 不传
device时用哪台生成配置码:给新设备用,一次性 + 倒计时 + 可撤销
修改后台密码:需要先输入当前密码
轮换 AUTH_TOKEN:自动生成或自定义,立即生效
轮换 AGENT_TOKEN:同样立即生效(之后要更新各设备配置)
界面是深色玻璃拟态风格,带弹性过渡动画、LED 呼吸灯、骨架屏加载,支持明暗主题切换
(跟随系统 + 手动切换,记在 localStorage),并且响应 prefers-reduced-motion。
凭证默认打码显示,要复制客户端配置时点「显示完整凭证」,看完可以再点回去隐藏。
令牌存在 Worker 的 Durable Object 里,优先级高于 Secrets,所以在网页上改完不用重新部署。
轮换后在设备上执行 tmcp token sync 就能把新 token 拉回本地。
本地还有个应急面板
tmcp panel(只监听 127.0.0.1),外网打不开 WebUI 时用。
三种凭证的分工
凭证 | 用途 | 存放 | 谁能看到 |
后台密码 | 登录 | PBKDF2 哈希(DO) | 只有你 |
AUTH_TOKEN | AI 客户端调 | DO / Secret | 后台点「显示」才看得到完整值 |
AGENT_TOKEN | 设备连 Worker | DO / Secret | 同上 |
工具清单(19 个 + 4 个设备管理)
工具 | 说明 |
| 非交互式命令(默认 30s,最长 45s) |
| 读写、精确替换(大文件自动分块) |
| 目录与文件管理 |
| 文件名 / 内容搜索 |
| 系统、发行版、CPU、内存、磁盘 |
| 真实 PTY( |
| 后台长任务,不受 45s 限制 |
| 列出所有设备与在线状态 |
| 某台设备的进程/系统详情 |
| 读某台设备的日志 |
| 强制某台设备重连 |
相对路径基于 $HOME,~/x 也支持。
多设备:所有工具都接受可选的 device 参数(设备 id)。不传则用默认设备。
{ "name": "run_command", "arguments": { "command": "docker ps", "device": "debian-vps" } }给 AI 的建议:普通命令用 run_command;要 TTY 用 shell_*;超过 45 秒用 job_start +
job_status(wait_ms=...) 轮询;大文件分段读;多设备先 list_devices。
命令
tmcp 交互菜单
tmcp setup 配置向导(可反复执行)
tmcp deploy 部署 / 更新 Worker 并同步 token
tmcp domain 绑定自有域名
tmcp start | stop | restart
tmcp status 本地 + Worker + 各设备
tmcp logs -f 跟日志
tmcp test 自检
tmcp doctor 环境体检
tmcp enroll [地址] [注册码] 用一次性配置码一键配置
tmcp admin-pass 设置 / 重置后台登录密码
tmcp token 查看 token
tmcp token sync 从 Worker 拉回当前 token(WebUI 轮换后用)
tmcp token rotate auth|agent
tmcp url <地址> 改 Worker 地址
tmcp panel 本地应急面板配置
~/.config/termux-mcp-remote/config.json(600)
字段 | 说明 |
| Worker 根地址(不要带 |
| AI 客户端用的 token |
| 设备连 Worker 用的 token(不要外泄) |
| 设备显示名 |
| 设备 id(默认由主机名派生,如 |
| 最大 PTY 会话数(默认 6) |
| PTY 空闲回收毫秒(默认 30 分钟) |
改完 tmcp restart。
安全模型
设备只主动外连,不监听任何公网端口
/mcp必须带正确 token,定长比较防时序攻击Agent 通道用独立的
AGENT_TOKEN同一 deviceId 只保留一条连接,新连接顶掉旧的,避免双写
delete/move拒绝操作/、$HOME、$PREFIX等根路径本身远程单条响应截断到 ~180KB;大消息自动切片(Cloudflare 单帧 1MiB 限制)
WebUI 需 AUTH_TOKEN;本地应急面板只监听
127.0.0.1
目录结构
agent/ 设备侧:连接 / 工具执行 / PTY / 后台任务 / CLI / 守护进程 / 平台探测
worker/ Cloudflare Worker:MCP 服务、多设备隧道、WebUI、OAuth、运行时设置
shared/ 两端共用:工具定义、WebSocket 分块传输
local/ 本地模拟服务器(不联网也能端到端验证)
scripts/ 验收测试
contrib/ systemd 服务模板
install.sh 安装 tmcp(自动适配 Termux / Debian / Linux)排障
现象 | 处理 |
设备显示离线 |
|
curl Worker 超时 |
|
401 | 请求头没带或 token 不匹配; |
忘记后台密码 |
|
后台密码输错被锁 | 等 10 分钟,或 |
部署后行为没变 | 已内置 build 检测:Agent 发现 Worker 换了代码会自动重连 |
手机重启后没连上 | Termux:Boot + 关闭电池优化 |
systemd 起不来 | 检查 |
PTY 打不开 |
|
命令超时 | 改用 |
调用报「正在自动重连」 | 网络抖动导致长连接重建,1-5 秒后重试 |
| Android 内核不导出 |
AUTH_TOKEN 与 Worker 不一致 |
|
两个值得记住的坑
tmcp restart 不能把自己杀掉。
早先把后台任务跑在独立进程组(detached: true),Agent 停机时 killAll() 的
process.kill(-pid) 会把「正在执行 restart」的那个进程一并杀掉——日志表现为
exit=null signal=SIGKILL,结果只停了没起。现在:
后台任务不再 detached,改用
trap '' HUP INT屏蔽挂断信号;restart先把「延时启动器」spawn(detached)到独立进程组,再执行 stop。 即使 restart 本身被杀,启动器也会在 1 秒后把服务拉起来。
AUTH_TOKEN 会被 WebUI 轮换,CLI 要能自愈。
/api/admin/reveal-token 额外接受设备凭证(AGENT_TOKEN)。理由:设备本来就能
执行任意命令、也能读到本地配置里的 token,所以这不算提权;好处是 AUTH_TOKEN 在
后台被轮换后,tmcp status 能自动取回并写回本地,不会卡在 401。
本地测试(不碰 Cloudflare)
node local/local-server.js # 模拟 Worker @ 127.0.0.1:29200
tmcp url http://127.0.0.1:29200 && tmcp start
node scripts/remote-test.mjs http://127.0.0.1:29200/mcp <AUTH_TOKEN>验收状态
实测环境:华为 LIO-AN00 / Termux / Node 24
scripts/remote-test.mjs(经公网 Worker):37 项全通过 —— 19 个工具、700KB 分块写入、大输出截断、PTY 交互、后台任务、错误处理scripts/oauth-test.mjs:23 项全通过 —— 元数据发现、动态注册、PKCE、密码校验、授权码一次性、refresh、401 语义scripts/multidevice-test.mjs:11 项全通过 —— 三设备同时在线、按 device 路由、不存在设备报错、单设备断开不影响其他scripts/admin-auth-test.mjs:18 项全通过 —— 首次设置、HttpOnly/SameSite cookie、密码与 token 互不通用、伪造会话被拒、改密后旧会话失效scripts/enroll-test.mjs:28 项全通过 —— 生成、兑换、一次性、过期即焚、撤销、TTL 钳制、码内不含密钥、列表不泄漏明文WebUI DOM 测试(jsdom):25 项全通过 —— 登录门、设备卡渲染、凭证打码/显示、主题切换、标签页、设备详情查询、控制台无错误
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
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Give your AI hands on every computer you own. Remote control of your Windows, Mac and Linux machines from one ChatGPT, Claude or Cursor chat — even from your phone. Ask it to find out why the office server is crawling, update every PC in the house, sort out your mom's laptop from another city, or ship the site from your work machine while you're on a train. It runs commands, reads files and takes a screenshot when it needs to see the screen. You decide what each computer allows, and you can cut any of them off in a second.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables external AI (ChatGPT, Claude) to securely access a local workspace via Cloudflare Tunnel, providing file operations, shell commands, Git operations, and more with bearer token authentication and sandbox isolation.1-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to securely connect to and execute commands on a remote Linux server via Cloudflare Tunnel, with bearer-token authentication.MIT
- AlicenseNot gradedqualityBmaintenanceEnables self-hosted remote control of your own computers from Claude and ChatGPT, allowing file management, terminal access, and process control on paired machines via an outbound WebSocket relay you host.7MIT
- AlicenseNot gradedqualityBmaintenanceEnables a cloud-hosted AI agent to execute shell commands, manage background jobs, and drive interactive persistent terminals on a remote Linux VPS with native root privileges over MCP and HTTPS — no SSH, tunnel, or local runtime required. It also provides bearer-key authentication, key revocation, and a LAN-restricted dashboard for sessions and audit logs.MIT