Remote Cmd

  ](https://github.com/nks-hub/remote-cmd) 

RemoteCmd v1.1.0

AI代理的远程命令执行中继。执行PowerShell命令，并通过HTTP轮询通过NAT/防火墙在远程计算机上传输文件。 多客户端支持 --单个中继可以服务于许多目标机器，并按名称将命令路由到特定的机器。

建筑

+---------------------+     +----------------------+     +---------------------+
|   MCP Client        |     |   Relay Server       |     |   Target Machines   |
|   (Claude Code)     |     |   (.NET 9.0)         |     |   (.NET 9.0)        |
|                     |     |                      |     |                     |
|  +---------------+  |     |  HTTP API :7890      |     |  +---------------+  |
|  | MCP Server    |--+-----+-> /api/exec          |     |  | Client A      |  |
|  | (Node.js)     |  |     |  /api/upload         |` 以特定机器为目标。
1. 这 **服务器** 在该客户端的会话上将命令排队，等待结果，然后返回。

客户端只需要出站HTTP。目标计算机上没有入站端口。

## 快速开始

### 1.启动中继服务器

dotnet run --project RemoteCmd.Server --

With env vars (useful for systemd, containers, tests):

REMOTECMD_TOKEN= REMOTECMD_NO_TLS=1 dotnet run --project RemoteCmd.Server

服务器正在监听 `http://0.0.0.0:7890` （或 `https://` 使用TLS）。令牌用于所有API端点上的身份验证。

### 2.在目标计算机上启动客户端

From source

dotnet run --project RemoteCmd.Client -- [--name ]

Or the published self-contained exe:

RemoteCmd.Client.exe --name comos-1

每个客户端将其GUID保存到 `%LOCALAPPDATA%\RemoteCmd\client..id` （Linux/macOS： `$XDG_DATA_HOME/RemoteCmd/` 或 `~/.local/share/RemoteCmd/`).ID在重新启动后仍然有效。id文件是 **范围按 `--name`**，因此同一台机器上的多个别名实例（例如提升+非提升）获得不同的id，并且不会竞争同一会话。遗产 `client.id` 将自动迁移默认计算机名实例。

### 3.为克劳德代码配置MCP

{ "mcpServers": { "remote-cmd": { "type": "stdio", "command": "node", "args": [" /mcp-server/index.mjs"], "env": { "REMOTECMD_URL": "https://localhost:7890", "REMOTECMD_TOKEN": "", "REMOTECMD_DEFAULT_CLIENT": "comos-1" } } } }

`REMOTECMD_DEFAULT_CLIENT` 是可选的--设置时，工具默认为该客户端，除非通过 `client` 争论。

### 4.通过卷发器使用

List all clients

curl "http://localhost:7890/api/clients?token="

Execute command on the single connected client (auto-select)

curl -X POST "http://localhost:7890/api/exec?token=" \ -H "Content-Type: application/json" \ -d '{"command":"hostname","timeoutSeconds":30}'

Target a specific client by name

curl -X POST "http://localhost:7890/api/exec?token=&client=comos-1" \ -H "Content-Type: application/json" \ -d '{"command":"hostname"}'

Upload file to a specific client

curl -X POST "http://localhost:7890/api/upload?token=&client=comos-1&path=C:\dest\file.zip" \ --data-binary @local.zip

## MCP工具

|工具|说明|
|------|-------------|
| `remote_list_clients` |列出所有已知的具有连接状态的客户端|
| `remote_status` |检查聚合或单个客户端状态|
| `remote_exec` |在目标客户端上执行PowerShell|
| `remote_upload` |将文件从本地上传到远程客户端（最大200MB）|
| `remote_download` |将文件从远程客户端下载到本地（最大200MB）|

除以下工具外的所有工具 `remote_list_clients` 接受可选 `client` 参数（名称或id）。如果省略，服务器会自动选择是否只连接了一个客户端；否则，将返回连接客户端列表的错误。

## API 参考

所有端点都需要一个令牌——通过 `?token=`, `X-Token: ` 标题，或 `Authorization: Bearer `.

### 控制器端点

|方法|端点|描述|
|--------|----------|-------------|
| `GET` | `/api/clients` |列出所有客户(`{count, connected, clients: [...]}`) |
| `GET` | `/api/status[?client=X]` |汇总状态；和 `client` 按客户详细信息返回|
| `POST` | `/api/exec[?client=X]` |执行命令 `{"command":"...","timeoutSeconds":30}` |
| `POST` | `/api/upload?path=[&client=X]` |上传文件（二进制正文）|
| `GET` | `/api/download?path=[&client=X]` |下载文件|

### 面向客户端的轮询端点

客户通过以下方式识别自己 `?clientId=&name=` 在每次投票请求中。

|方法|端点|描述|
|--------|----------|-------------|
| `GET` | `/api/poll` |轮询挂起的命令（加密）|
| `POST` | `/api/result` |发布加密命令结果|
| `GET` | `/api/file-poll` |轮询待处理的文件传输|
| `GET` | `/api/file-data` |下载文件数据以上传到远程|
| `POST` | `/api/file-done` |确认文件已保存|
| `POST` | `/api/file-upload` |上传文件数据以从远程下载|

### 目标分辨率规则

1. 如果 `?client=` 已指定→ 该会话（如果未知则为404，如果未连接则为400）。
1. 否则，如果只连接了一个客户端→ 那个。
1. Else → 列出连接的客户端名称时出错。

## 构建

Build + test

dotnet build RemoteCmd.sln dotnet test RemoteCmd.sln

MCP tests

cd mcp-server && npm install && npm test

Publish self-contained client

dotnet publish RemoteCmd.Client -c Release -r win-x64 --self-contained \ -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true \ -o publish/client

## 环境变量

|变量|位置|默认值|描述|
|----------|-------|---------|-------------|
| `REMOTECMD_TOKEN` |服务器，MCP|--|共享身份验证令牌|
| `REMOTECMD_NO_TLS` |服务器|未设置| `1`/`true` 禁用TLS（回退时 `--no-tls` 未通过）|
| `REMOTECMD_URL` |MCP| `https://localhost:7890` |中继URL|
| `REMOTECMD_DEFAULT_CLIENT` |MCP|未设置|目标客户端的名称或id `client` arg被省略|

## 安全

|层|技术|范围|
|-------|-----------|-------|
|传输|TLS 1.2+（自签名证书）|服务器↔ 客户端HTTPS|
|有效载荷|AES-256-GCM|所有命令、结果、文件数据、元数据|
|身份验证|共享令牌，恒定时间比较|全部 `/api/*` 端点|

令牌可以通过以下方式传递 `?token=`, `X-Token:` 标题，或 `Authorization: Bearer`.在生产环境中更喜欢标头或承载形式——查询字符串会泄漏到代理日志中。

使用 `--no-tls` （或 `REMOTECMD_NO_TLS=1`)在服务器上用于仅HTTP模式（AES有效载荷加密保持活动状态）。

## 技术细节

|参数|值|
|-----------|-------|
|客户端轮询间隔|800毫秒|
|命令超时|每个请求可配置（默认30秒，最大300秒）|
|进程终止超时|60秒（客户端）|
|文件传输超时|5分钟|
|最大文件大小/正文|200 MB|
|自动重新连接|指数回退（1秒→ 30 s) |
|并发|每个客户端 `SemaphoreSlim(1)` --每台机器串行，多台机器并行|
|壳牌| `powershell.exe -NoProfile -NonInteractive` |
|客户端检测|如果上次轮询\NKS Hub