mcp-remote-control
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-remote-controlRunuptimeon the staging server"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-remote-control
通过 MCP 管理本机 / SSH / WinRM 远端主机;业务在 Core,MCP / CLI 只做薄壳。会话与 endpoint 均为进程内状态。
入口 | 作用 |
| MCP stdio 服务(Claude Code / Cursor / Claude Desktop 等 Host) |
| 同构 CLI harness(doctor / 调试 / 与 MCP 共用 Core) |
MCP 工具(7):
类 | 工具 |
主机 |
|
设备 |
|
自助配置 |
|
要求: Python ≥ 3.11 · 依赖 asyncssh · pyte · pypsrp · mcp · pyserial
名称 | 值 |
发行包 / MCP 服务名 |
|
import |
|
配置根(默认) |
|
Git / 工程根 | 本目录(含 |
许可证 | Apache-2.0(可商用;再分发须保留版权/许可与 |
目录
Related MCP server: CommandBridge MCP
Agent 输出形态(MCP wire)
规范上 tools/call 应返回 纯文本 content,例如:
{
"content": [{ "type": "text", "text": "@exec ok ep=lab exit=0 …\n\n$ whoami\n…" }],
"isError": false
}本项目默认 Agent 轨(语义文本,见设计 002):
@exec ok ep=lab exit=0 ms=12 form=command cwd=/home/deploy
$ whoami
deploy不是默认把正文塞进:
{ "result": "@exec ok …" }那一层 {"result":…} 来自 FastMCP 对 -> str 的自动 structuredContent 包装。本仓库在 tool 注册时使用 structured_output=False,只暴露 Agent 文本,避免 Host UI 显示 JSON 外壳。
CLI 默认同样是 Agent 文本;加 --json 才走机器轨。
三种装法(先选场景)
你想做什么 | 命令形态 | 改 | README 小节 |
只使用(Host 挂公开/私有 GitHub,不改源码) |
| 否(吃 cache;远端更新要 | |
改源码开发(editable) | 先 clone 到本地,再 | 是(仍须重启 MCP 进程) | |
长期本机 CLI |
| tool 安装否 / |
重要:editable 不能直接挂 GitHub URL。
# ❌ 不要这样想:把 GitHub 地址当 editable
uvx --with-editable "git+https://github.com/shiharuharu/mcp-remote-control.git" ...
# uv 的 --with-editable / pip -e 需要的是「本地目录」
# (含 pyproject.toml 的 checkout),不是远程 URL。想「对着 GitHub 上的仓改代码」时,正确路径是:
git clone https://github.com/shiharuharu/mcp-remote-control.git
cd mcp-remote-control # 本仓库:含 pyproject.toml 的根(即本目录)
REPO="$(pwd)"
uvx --python 3.12 --with-editable "$REPO" --from "$REPO" mcp-remote-control快速部署(推荐:uvx + Git)
uv 的 uvx 按需拉包并在隔离环境运行入口,适合 MCP Host 的 command / args。
1. 配置目录
mkdir -p ~/.config/mcp-remote-control/{profiles,secrets,state,logs}
export MRC_HOME="$HOME/.config/mcp-remote-control"最小 config.toml / profile 见 配置 MRC_HOME。也可交给 Agent:config ensure_home → put_secret → put_profile。
2. 从 Git 运行(只用)
本目录即仓库根。官方地址:https://github.com/shiharuharu/mcp-remote-control(**不要** #subdirectory=)。
这是 「Host 直接挂 GitHub」 的用法:--from git+…,不是 editable。
FROM="git+https://github.com/shiharuharu/mcp-remote-control.git@main"
# MCP stdio(由 Host 拉起;前台会等待协议输入)
uvx --python 3.12 --from "$FROM" mcp-remote-control
# CLI 自检
uvx --python 3.12 --from "$FROM" mcp-remote-control-cli doctor
uvx --python 3.12 --from "$FROM" mcp-remote-control-cli endpoint list分支 / tag / commit / 私有仓:
uvx --python 3.12 --from "git+https://github.com/shiharuharu/mcp-remote-control.git@v0.1.0" mcp-remote-control
uvx --python 3.12 --from "git+https://github.com/shiharuharu/mcp-remote-control.git@abcdef1" mcp-remote-control
uvx --python 3.12 --from "git+ssh://git@github.com/shiharuharu/mcp-remote-control.git@main" mcp-remote-control
uvx会缓存环境。 远端或本地源码更新后工具列表仍旧(例如缺config、仍有{"result":…})时:
加
--refresh,或pin 新 commit/tag,或
开发期 clone 后 用下面的
--with-editable本地路径 / 直接跑.venv入口。
3. 固定安装(可选)
uv tool install --python 3.12 --from "git+https://github.com/shiharuharu/mcp-remote-control.git@main" mcp-remote-control
# 入口常在 ~/.local/bin/mcp-remote-control
uv tool upgrade mcp-remote-control本地开发(必读:--with-editable)
开发时若只用:
uvx --from /path/to/this-repo mcp-remote-control
# 或:uvx --from "git+https://github.com/shiharuharu/mcp-remote-control.git@main" …uvx 会把包拷进 cache,不会随你改 src/ 自动更新 → Host 可能仍是旧 6 tools(无 config)、旧 structured 包装。
推荐 A:clone 后 uvx --with-editable(跟源码联动)
从 GitHub 拉到本地(或已有 fork/checkout)。
--with-editable/--from都填本地绝对路径(含pyproject.toml的目录 = 本仓库根)。
# 若还没有本地树:
git clone https://github.com/shiharuharu/mcp-remote-control.git
cd mcp-remote-control # 仓库根(本目录)
REPO="$(pwd)" # 或 /abs/path/to/mcp-remote-control
# 每次从源码可编辑安装再跑入口(改代码后重启 MCP 进程即可)
uvx --python 3.12 \
--with-editable "$REPO" \
--from "$REPO" \
mcp-remote-control
# CLI
uvx --python 3.12 \
--with-editable "$REPO" \
--from "$REPO" \
mcp-remote-control-cli doctor参数 | 作用 |
| 用本地项目提供 console script( |
| 以 editable 装本包,改 |
| 满足 |
| 丢掉 uv 缓存元数据后重装(排障时用) |
也可:
cd "$REPO"
uvx --python 3.12 --with-editable . --from . mcp-remote-control-cli config home推荐 B:venv 入口(最稳、Host 配置最简单)
cd /path/to/this-repo
uv venv --python 3.12
source .venv/bin/activate # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
export MRC_HOME="$HOME/.config/mcp-remote-control"
mcp-remote-control-cli doctor
mcp-remote-control # stdioHost 直接指向:
/path/to/this-repo/.venv/bin/mcp-remote-control推荐 C:uv run(在项目目录内)
cd /path/to/this-repo
uv run --python 3.12 mcp-remote-control-cli doctor
uv run --python 3.12 mcp-remote-control不要这样做(开发)
做法 | 问题 |
仅 | 易吃 旧 cache 快照,新工具/修复不出现 |
改完代码不重连 MCP | stdio 进程仍是旧内存;需 Host 重连 |
系统 Python 3.9 调 |
|
MCP Host 配置
command = 本机可执行文件(which uvx 或 venv 绝对路径),env.MRC_HOME 指向配置根。
生产 / 只用:远端 GitHub(非 editable)
Host 里写 Git URL,用 --from git+…。不要在 args 里写 --with-editable + git+https://…。
{
"mcpServers": {
"mcp-remote-control": {
"command": "uvx",
"args": [
"--python", "3.12",
"--from",
"git+https://github.com/shiharuharu/mcp-remote-control.git@main",
"mcp-remote-control"
],
"env": {
"MRC_HOME": "/Users/<you>/.config/mcp-remote-control"
}
}
}
}强制刷新缓存(远端更新后 Host 仍旧时):
"args": [
"--python", "3.12",
"--refresh",
"--from",
"git+https://github.com/shiharuharu/mcp-remote-control.git@main",
"mcp-remote-control"
]开发:本地 checkout + --with-editable(推荐)
先 git clone(或本机已有树),args 里 只填本地绝对路径:
{
"mcpServers": {
"mcp-remote-control": {
"command": "uvx",
"args": [
"--python", "3.12",
"--with-editable",
"/Users/<you>/src/mcp-remote-control",
"--from",
"/Users/<you>/src/mcp-remote-control",
"mcp-remote-control"
],
"env": {
"MRC_HOME": "/Users/<you>/.config/mcp-remote-control"
}
}
}
}路径 = 含 pyproject.toml 的仓库根(本项目即本目录)。改代码后 重连 MCP,不要指望 stdio 进程热更新。
开发:venv 绝对路径(最简单)
{
"mcpServers": {
"mcp-remote-control": {
"command": "/Users/<you>/repo/.../code-root/.venv/bin/mcp-remote-control",
"args": [],
"env": {
"MRC_HOME": "/Users/<you>/.config/mcp-remote-control"
}
}
}
}Claude Desktop
编辑 mcpServers(macOS 常见:~/Library/Application Support/Claude/claude_desktop_config.json),键名建议 mcp-remote-control,结构同上。
Claude Code(全局示例)
常见:~/.claude.json → mcpServers(字段同上)。改完后 重连 MCP,确认 tools 为 7 个且含 config。
部署后自检
export MRC_HOME="$HOME/.config/mcp-remote-control"
# 应列出 7 名:endpoint,exec,fs,screen,ps,console,config
uvx --python 3.12 --with-editable . --from . mcp-remote-control-cli doctorHost 侧:重连后工具列表须含 config;调用结果应为 @kind … 文本,不应再被 {"result":…} 包一层。
配置 MRC_HOME
路径 | 含义 |
| 全局默认 |
| 每个 endpoint 一个 profile( |
| 密钥/密码文件(勿提交 Git) |
| 运行时状态 |
| 日志 |
环境变量 | 含义 |
| 配置根(优先) |
| 次选别名 |
(皆未设) |
|
transport:local | ssh | winrm
local / ssh ≈
exec+fs+screenwinrm ≈
exec+fs+ps(screen→ UNSUPPORTED)
手写示例
# $MRC_HOME/config.toml
[defaults]
verbosity = "normal"
[logging]
level = "info"
dir = "logs"# $MRC_HOME/profiles/local.toml
name = "local"
transport = "local"
label = "this machine"# $MRC_HOME/profiles/lab-ssh.toml
name = "lab-ssh"
transport = "ssh"
host = "10.0.0.5"
port = 22
username = "deploy"
label = "lab"
[auth]
method = "private_key_path"
key_path = "secrets/id_ed25519" # 相对 MRC_HOME 或绝对路径
[ssh]
connect_timeout_ms = 15000
keepalive_interval_s = 30
known_hosts = "none" # 仅实验室;生产请用 known_hosts 文件
encoding = "utf-8"
[defaults]
cwd = "/home/deploy"密钥:chmod 600 $MRC_HOME/secrets/*。密码可用 password_path = "secrets/lab_pass"。
Agent 自助配置(优先)
config op=ensure_home
config op=put_secret name=id_ed25519 content=<pem 或密码>
config op=put_profile name=lab transport=ssh host=… username=…
auth={"method":"private_key_path","key_path":"secrets/id_ed25519"}
endpoint op=open profile=lab
| 作用 |
| 查看 / 创建布局 + 默认 |
| 读配置(无密钥正文) |
| 写/删 |
| 写密钥(只回路径)/ 列文件名 |
密钥 只 进 secrets/,响应永不回 body。
工具面(给 Agent)
主机
Tool | 作用 |
|
|
| 非交互: |
|
|
| 真 PTY(需 |
| WinRM 持久 PowerShell(需 |
典型:endpoint open → exec / fs / screen → close。
Console(独立 — 嵌入式串口)
与 endpoint 完全分离。不是 PTY、不是 SSH。open 即后台 CapturePump;views 查大缓冲。
console op=list
console op=open path=<device> baud=115200
console op=views id=con_01 mode=tail|since|contains
console op=send id=con_01 data=… newline=true
console op=close id=con_01op | 含义 |
| 系统 console 设备名(禁止扫 |
|
|
|
|
|
|
| 关闭 / 列会话 |
Config
见上一节 Agent 自助配置。
CLI
mcp-remote-control-cli 是 MCP 的平行入口:同一套 Core,无 MCP 依赖;适合本地调试、脚本和 CI harness。业务逻辑不在 CLI 里重写。
入口 | 命令 | 进程模型 |
MCP Host |
| Host 拉起一个长进程,会话挂在该进程内 |
CLI harness |
| 每次调用通常是新进程(见下方进程内限制) |
默认输出与 MCP 相同的 Agent 文本;加全局 --json 走机器轨。
MCP tool ↔ CLI 对照
MCP 侧是「一个 tool + op=」;CLI 侧是「子命令 + 二级 op」。语义对齐,参数名多为 --flag 形式。
MCP tool | CLI | 典型 op / 子命令 | 说明 |
|
|
| 主机生命周期; |
|
|
| 非交互执行;也可用 |
|
|
| 需已 open 的 |
|
|
| 真 PTY;见进程内限制 |
|
|
| WinRM 持久 PS;会话进程内 |
|
|
| 串口,非 PTY/SSH |
|
|
| 写 |
仅 CLI / harness(MCP 无对应 tool):
CLI | 用途 |
| 离线:配置根、依赖、profile 语法;可选 |
| 离线 smoke:render 往返 + fixture 配置加载 |
| PTY fixture 回放(CI;无真 TUI)。例: |
进程内状态限制(必读)
endpoint / screen / ps / console 的打开会话只存在于当前 Python 进程。
场景 | 结果 |
MCP:Host 同一 stdio 进程内 | 正常 |
CLI:同一次命令里完成的操作 | 正常(单进程) |
CLI: |
|
多进程 CLI 接力 endpoint/ps/console 会话 | 同样失败 |
因此:
人工调试 screen:用 MCP Host 一次会话;或仓库内
scripts/harness/local_screen_smoke.py/smoke_local.sh(进程内 open→send→close)。CI:
ci.sh用 in-process smoke +replay,不用跨进程 CLI 拼 screen。
# ❌ 不要这样(两次进程,第二次找不到 session)
mcp-remote-control-cli screen open --ep local
mcp-remote-control-cli screen send --id scr_01 --text 'ls'
# ✅ MCP 同一连接内连续 tool call;或:
./scripts/harness/smoke_local.sh示例
export MRC_HOME="$HOME/.config/mcp-remote-control"
# harness 专用
mcp-remote-control-cli doctor
mcp-remote-control-cli selftest
mcp-remote-control-cli replay --fixture bash_prompt --check
# 与 MCP 同构
mcp-remote-control-cli endpoint list
mcp-remote-control-cli endpoint open --profile local
mcp-remote-control-cli exec --ep local --command 'uname -a'
mcp-remote-control-cli fs list --ep local --path /tmp
mcp-remote-control-cli console list
mcp-remote-control-cli config home
mcp-remote-control-cli config ensure-home
mcp-remote-control-cli config list-profiles
mcp-remote-control-cli config put-secret --name id_ed25519 --content "$(cat ./id_ed25519)"
mcp-remote-control-cli config put-profile --name lab --transport ssh \
--host 10.0.0.5 --username deploy \
--auth-json '{"method":"private_key_path","key_path":"secrets/id_ed25519"}'
# 机器轨
mcp-remote-control-cli --json endpoint list完整 flag:mcp-remote-control-cli <cmd> -h / … <cmd> <op> -h。
开发与 harness
工程根 = 本目录(pyproject.toml / src/ / tests/)。
export MRC_HOME="$(pwd)/tests/fixtures/config"
uv venv --python 3.12 && source .venv/bin/activate
uv pip install --python .venv/bin/python -e ".[dev]" # 含 pytest + ruff==0.15.12
ruff check src tests
./scripts/harness/ci.shci.sh:pytest(无 integration)→ doctor/selftest → smoke_local / smoke_mcp → replay。
GitHub Actions(已写好,推仓后生效): .github/workflows/ci.yml
Job | 内容 |
| 矩阵 Python 3.11 / 3.12 / 3.13: |
|
|
触发:push/pull_request 到 main/master,以及 workflow_dispatch。
本地等价:./scripts/harness/ci.sh(单版本;全量矩阵靠 Actions)。
可选 | 说明 |
| 真机集成测 |
| Docker 方言矩阵 |
.
├── LICENSE # Apache-2.0
├── NOTICE # attribution (must travel with redistributions)
├── pyproject.toml # name = mcp-remote-control
├── README.md
├── .github/workflows/ci.yml
├── src/mcp_remote_control/
├── tests/
└── scripts/harness/其它安装:
pip install "git+https://github.com/shiharuharu/mcp-remote-control.git@main"
python -m mcp_remote_control.mcp_server故障排查
现象 | 原因 / 处理 |
找不到 | Host 仍在跑 旧 uvx 缓存(仅 6 tools)。改用 本地 |
想 editable 却写了 | uv 的 editable 只接受本地路径。先 |
输出被 | 旧 FastMCP structured 包装;当前源码已 |
| 旧 probe 把 |
| 加 |
私有仓认证失败 |
|
| 检查 |
| 会话仅在当前 Python 进程内。勿跨两次 CLI 进程接力 |
远端/源码已更新 Host 仍旧 |
|
WinRM | 预期 |
GitHub Actions 不跑 | 工作流在 本目录 |
验证 tools 是否最新(在仓库根):
uvx --python 3.12 --with-editable . --from . python -c \
"from mcp_remote_control.mcp_server import tool_names; print(tool_names())"
# 期望: ['endpoint', 'exec', 'fs', 'screen', 'ps', 'console', 'config']安全提示
密钥只放
$MRC_HOME/secrets/,勿写进 profile 明文、勿提交 Git。Agent 轨会 redact 常见敏感字段;不要把私钥/密码当普通日志贴出。
put_secret的 content 只应在 tool 参数中传递一次,响应里不会回显 body。生产 SSH 慎用
known_hosts = "none"。仓库内
tests/fixtures/config/secrets/*仅为 dummy 测试夹具(见该目录README.md),不是可用密钥。
许可证
本项目以 Apache License 2.0 发布,归属说明见 NOTICE。
可以 | 约束(再分发时「必须带上」) |
商用、闭源产品内嵌、SaaS 使用 | 附带本 LICENSE 副本 |
修改源码并再分发 | 修改过的文件标明已变更 |
申请专利交叉许可(见协议正文) | 保留 原有版权 / 专利 / 商标 / 归属声明 |
若附带 NOTICE,衍生作品须按 4(d) 继续携带 其中的归属信息 |
不是 GPL: 你的专有代码不必开源;Apache-2.0 不强制衍生作品整体以同一许可证发布,但不能剥掉本项目自带的许可与 NOTICE 要求。
名称对照
用途 | 名称 |
产品 / 发行包 / MCP 服务 | mcp-remote-control |
MCP console script |
|
CLI console script |
|
Python 包 / import |
|
配置根默认 |
|
环境变量 |
|
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Servers
- Flicense-qualityCmaintenanceMCP server for infrastructure discovery and remote management, enabling SSH command execution, file transfer, log tailing, and machine/service inventory with a companion web dashboard.Last updated1
- FlicenseAqualityBmaintenanceCross-platform MCP server for policy-controlled command execution on Linux and Windows, with no SSH dependency.Last updated3
- Alicense-qualityCmaintenanceMCP server for administering Linux/Unix hosts via SSH and Windows hosts via WinRM/PowerShell Remoting, supporting persistent inventory, sessions, jobs, and command groups.Last updatedMIT
- Alicense-qualityCmaintenanceA production-ready MCP server for secure, session-based command execution, file manipulation, and system inspection via local terminal sessions.Last updated12ISC
Related MCP Connectors
Tailscale device, route, DNS, key, user, and ACL management over MCP and CLI.
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
An MCP server that let you interact with Cycloid.io Internal Development Portal and Platform
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/shiharuharu/mcp-remote-control'
If you have feedback or need assistance with the MCP directory API, please join our Discord server