Remote Cmd Server

一个支持 streamable-http 传输的 MCP (Model Context Protocol) 服务器，用于在远程部署服务器上执行预配置的指令。每个命令自动注册为独立的 MCP Tool，无需先查询再执行。

功能特性

• 支持 MCP streamable-http 传输协议
• 通过 JSON 配置文件管理命令，自动注册为独立 MCP Tool
• SK (Secret Key) 安全校验，支持时间戳防重放
• 安全的命令执行（预配置命令，非任意命令）
• 支持命令超时控制
• 动态重载配置（运行时更新工具列表）

项目结构

remote-cmd-mcp-server/
├── mcp_server.py       # MCP 服务器主程序
├── commands.json       # 命令配置文件
├── .sk                 # SK 密钥配置（不提交到 Git）
├── .sk.example         # SK 配置示例
├── requirements.txt    # Python 依赖
├── .gitignore          # Git 忽略规则
└── README.md           # 本文档

安装

方式一：使用 uv（推荐）

uv 是新一代 Python 包管理器，比 pip 更快。

# 安装 uv（如果还没有）
# Linux/macOS:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 创建虚拟环境并安装依赖（一条命令搞定）
uv venv && uv pip install -r requirements.txt

# 运行
uv run python mcp_server.py

方式二：使用 pip + venv

# Python 3.8+
python -m venv venv

# 激活虚拟环境
# Linux/macOS:
source venv/bin/activate

# Windows:
venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

配置

1. 命令配置 (commands.json)

每个命令会自动注册为一个独立的 MCP Tool，工具名直接使用命令 key（- 替换为 _）。建议使用统一前缀命名，如 remote_server_cmd_，避免与其他 MCP Server 工具名冲突。

{
    "commands": {
        "remote_server_cmd_hi": {
            "command": ["echo", "hello world"],
            "description": "输出 hello world"
        },
        "remote_server_cmd_date": {
            "command": ["date"],
            "description": "显示当前日期时间"
        },
        "remote_server_cmd_update_blog": {
            "command": ["bash", "-c", "cd /root/blog && git pull && docker compose up -d --build"],
            "description": "更新个人博客"
        }
    }
}

字段	类型	描述
key	string	命令标识，同时作为 MCP Tool 名称（如 remote_server_cmd_hi）
command	array	要执行的命令及参数
description	string	命令描述，会作为 Tool 的描述展示给 MCP Client

2. SK 安全配置 (.sk)

创建 .sk 文件启用接口鉴权：

# 复制示例文件
cp .sk.example .sk

# 编辑 .sk，设置你的密钥
# {
#     "secret_key": "your-secret-key-here"
# }

• .sk 文件已在 .gitignore 中，不会提交到版本库
• 如果 .sk 不存在或 secret_key 为空，SK 校验自动禁用
• SK 校验支持时间戳防重放攻击（默认 5 分钟有效期）

启动 MCP Server

# streamable-http 模式（默认，远程部署推荐）
python mcp_server.py --transport streamable-http

# 指定配置文件和 SK 文件
python mcp_server.py --config commands.json --sk .sk

# stdio 模式（本地 Claude Desktop 使用）
python mcp_server.py --transport stdio

# 查看帮助
python mcp_server.py --help

宿主机后台部署（生产环境推荐）

# 安装依赖
uv venv && source .venv/bin/activate && uv pip install -r requirements.txt

# 使用 nohup 后台运行
nohup .venv/bin/python mcp_server.py --transport streamable-http > mcp_server.log 2>&1 &

systemd 服务（推荐）

创建 /etc/systemd/system/mcp-server.service：

[Unit]
Description=Remote Command MCP Server
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/mcp-server
ExecStart=/opt/mcp-server/.venv/bin/python mcp_server.py --transport streamable-http
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable mcp-server
sudo systemctl start mcp-server
sudo systemctl status mcp-server   # 查看状态
journalctl -u mcp-server -f        # 查看日志

MCP Client 调用

方式一：使用 MCP SDK (Python)

from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
import time

async def main():
    headers = {}
    # 如果启用了 SK 校验
    headers["x-api-key"] = "your-secret-key-here"
    headers["x-timestamp"] = str(int(time.time()))

    async with streamablehttp_client(
        "http://your-server:8080/mcp",
        headers=headers
    ) as (read_stream, write_stream, _):
        async with ClientSession(read_stream, write_stream) as session:
            await session.initialize()

            # 列出所有可用工具（commands.json 中的每个命令 + reload_config）
            tools = await session.list_tools()
            print([t.name for t in tools.tools])

            # 直接调用命令，工具名就是命令 key
            result = await session.call_tool("remote_server_cmd_hi")
            print(result)

            result = await session.call_tool("remote_server_cmd_update_blog")
            print(result)

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

方式二：Claude Desktop 配置（HTTP 模式）

{
    "mcpServers": {
        "remote-cmd": {
            "url": "http://your-server:8080/mcp",
            "headers": {
                "x-api-key": "your-secret-key-here"
            }
        }
    }
}

方式三：Claude Desktop 配置（stdio 模式）

{
    "mcpServers": {
        "remote-cmd": {
            "command": "python",
            "args": ["/path/to/mcp_server.py", "--transport", "stdio"]
        }
    }
}

方式四：使用 curl 测试

# 初始化连接
TS=$(date +%s)
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: your-secret-key-here" \
  -H "x-timestamp: $TS" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'

可用工具

commands.json 中的每个命令会自动注册为一个 MCP Tool，工具名为命令 key。例如：

工具名	对应命令 key	描述
remote_server_cmd_hi	remote_server_cmd_hi	输出 hello world
remote_server_cmd_date	remote_server_cmd_date	显示当前日期时间
remote_server_cmd_hostname	remote_server_cmd_hostname	显示主机名
remote_server_cmd_update_blog	remote_server_cmd_update_blog	更新个人博客

此外还有一个内置工具：

reload_config

重新加载配置文件，动态更新可用工具列表。

参数：

• config_path (string, optional): 配置文件路径，默认 commands.json

安全说明

1. SK 校验：支持 x-api-key 或 Authorization: Bearer 两种 header 传递密钥
2. 时间戳防重放：通过 x-timestamp header 校验请求时效性（默认 5 分钟）
3. 命令白名单：只能执行配置文件中预定义的命令
4. 命令超时：所有命令默认 30 秒超时
5. 建议：
   • 生产环境务必配置 SK
   • 使用 HTTPS 或 VPN 保护传输链路
   • 使用 systemd 管理进程，配置自动重启

常见问题

Q: Windows 下命令不工作？

{
    "remote_server_cmd_ip": {"command": ["ipconfig"], "description": "显示 IP 配置"},
    "remote_server_cmd_dir": {"command": ["cmd", "/c", "dir"], "description": "列出目录"}
}

Q: 如何在宿主机执行 docker compose？

{
    "remote_server_cmd_deploy": {
        "command": ["bash", "-c", "cd /opt/myapp && docker compose up -d --build"],
        "description": "部署应用"
    }
}

注意：MCP Server 需要部署在宿主机上（而非 Docker 容器内），才能直接执行宿主机的 docker 命令。

Q: 如何运行多步命令？

使用 bash -c 将多条命令串联：

{
    "remote_server_cmd_update_blog": {
        "command": ["bash", "-c", "cd /root/blog && git pull && docker compose up -d --build"],
        "description": "拉取代码并重新部署博客"
    }
}

Q: SK 校验失败？

• 检查 .sk 文件是否存在且 secret_key 不为空
• 检查 x-api-key header 是否正确传递
• 检查 x-timestamp 是否在 5 分钟有效期内

License

MIT