Remote Session Mcp

Remote Session MCP Server

一个 Model Context Protocol（MCP）服务，可让 AI 助手管理持久化 SSH 会话并在远程服务上执行命令。

主要优势

带状态的持久化会话

与每次独立执行单条命令的 SSH 工具不同，此服务使用 invoke_shell() 维护交互式 Shell 会话，状态会在多条命令之间持续保留：

能力	持久化会话	单命令
工作目录（cd）	持续保留	每条命令执行后丢失
环境变量（export）	持续保留	每条命令执行后丢失
多步工作流	流畅自然	需要手动传递上下文
AI 上下文感知	自动跟踪 pwd	不跟踪状态

典型工作流：

create → execute("cd /app") → execute("export ENV=prod") → execute("./deploy.sh") → close

这非常适合 AI 驱动的部署、调试和服务器管理任务，因为这些任务中的命令彼此关联。

自动集成 SSH 配置

• 自动解析 ~/.ssh/config 中的连接参数
• 支持基于密钥的身份验证、自定义端口、跳板主机和所有标准 SSH 选项
• 无需硬编码凭据或连接详情

安装

# Using uv (recommended)
uv pip install -e .

# Or using pip
pip install -e .

使用方法

1. 配置 SSH

确保服务器已配置在 ~/.ssh/config 中：

Host production
    HostName 192.168.1.100
    User deploy
    IdentityFile ~/.ssh/id_rsa

2. 运行 MCP 服务

remote-session-mcp
# Or: python -m remote_session_mcp

3. Claude Code 集成

在项目中创建 .claude/settings.json 或 mcp.json：

{
  "mcpServers": {
    "remote-session": {
      "command": "uv",
      "args": ["run", "remote-session-mcp"],
      "cwd": "/path/to/sshmcp"
    }
  }
}

4. 可用工具

工具	描述
hosts	列出 ~/.ssh/config 中的所有主机
create	创建持久化 SSH 会话
execute	执行命令（状态持续保留）
close	关闭会话
sessions	列出活动会话
upload	将文件上传到远程服务
download	从远程服务下载文件

示例：部署应用程序

// 1. Create session
{"tool": "create", "arguments": {"host": "production"}}

// 2. Navigate and deploy (state persists)
{"tool": "execute", "arguments": {"session_id": "session_abc", "command": "cd /var/www/myapp"}}
{"tool": "execute", "arguments": {"session_id": "session_abc", "command": "git pull"}}
{"tool": "execute", "arguments": {"session_id": "session_abc", "command": "npm install"}}
{"tool": "execute", "arguments": {"session_id": "session_abc", "command": "sudo systemctl restart myapp"}}

// 3. Close session
{"tool": "close", "arguments": {"session_id": "session_abc"}}

配置（可选）

创建 ~/.remote-session/config.json 以使用自定义设置：

{
  "enable_raw_output": false,
  "ssh_config_path": "~/.ssh/config"
}

选项	默认值	描述
enable_raw_output	false	返回仅移除 ANSI 代码的原始输出
ssh_config_path	~/.ssh/config	SSH 配置文件的自定义路径

限制

• 仅支持 Linux/POSIX - 假定使用兼容 POSIX 的 Shell 和命令（pwd、echo $?）
• 需要交互式 Shell - 远程服务必须支持交互式 Shell 会话
• 会话超时 - 会话在闲置 1 小时后自动关闭（可配置）