SSH Agent MCP服务 - 支持SSH连接管理、命令执行和SFTP文件传输的完整MCP服务器

These details have not been verified by PyPI

Project links

Project description

SSH Agent MCP 服务

这是一个基于Python的MCP (Model Context Protocol) stdio服务，允许大模型直接操作SSH连接来解决远程服务器问题。支持通过命令行参数或JSON配置文件管理SSH连接，让用户通过简单的JSON配置即可使用。

功能特性

⚡ uvx支持: 通过 uvx ssh-agent-mcp 一键运行，无需本地安装
🔧 命令行参数: 支持完整的命令行参数配置，无需配置文件
🔧 JSON配置管理: 通过简单的JSON文件管理多个SSH连接
🔗 有状态连接管理: 维护SSH连接状态，支持多个并发连接
🔐 多种认证方式: 支持密码认证、私钥认证和SSH Agent
⚡ 命令执行: 在远程服务器上执行命令并获取输出
🔄 异步命令支持: 支持长时间运行的命令（如top、tail等），实时获取输出
🎮 交互式命令支持: 支持需要用户输入的交互式命令（如sudo、vim、mysql、python等）
📊 命令生命周期管理: 启动、监控、终止和清理异步命令和交互式会话
📈 连接状态查询: 实时查询连接状态和管理连接
🚀 自动连接: 支持启动时自动连接指定的服务器
📁 SFTP文件传输: 支持文件上传、下载和目录操作
📂 远程文件管理: 支持远程目录浏览、创建、删除和重命名

🚀 快速开始

方法一：uvx 一键运行（推荐）

在Claude Desktop的配置文件中添加：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": [
        "ssh-agent-mcp@latest",
        "--host=192.168.1.100",
        "--user=root",
        "--password=your_password",
        "--timeout=30000"
      ]
    }
  }
}

重启Claude Desktop即可使用！

⭐ 新特性：无参数启动

MCP服务可以不传入任何SSH连接参数启动，等待大模型通过工具提供连接信息：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": ["ssh-agent-mcp@latest"]
    }
  }
}

启动后，大模型可以使用 ssh_connect 或 ssh_connect_by_name 工具建立连接。

方法二：本地安装

# 安装
pip install ssh-agent-mcp

# 或从源码安装
git clone https://github.com/yourusername/sshagent.git
cd sshagent
pip install -e .

方法三：使用配置文件

创建配置文件 ssh_config.json:

{
  "connections": [
    {
      "name": "production-server",
      "host": "prod.example.com",
      "username": "admin",
      "private_key": "/home/user/.ssh/id_rsa",
      "tags": ["production"]
    }
  ],
  "auto_connect": ["production-server"]
}

在Claude Desktop中配置:

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": [
        "ssh-agent-mcp@latest",
        "--config=/path/to/ssh_config.json",
        "--connection=production-server",
        "--auto-connect"
      ]
    }
  }
}

📝 使用方式

方式一：无参数启动（推荐）⭐

最灵活的方式，启动时不传入任何连接参数，由大模型动态管理连接：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": ["ssh-agent-mcp@latest"]
    }
  }
}

优势：

🔄 动态连接管理：大模型可以根据需要连接不同的服务器
🛡️ 安全性更高：不在配置文件中暴露敏感信息
🎯 灵活性强：支持多服务器切换，适合复杂场景

方式二：纯命令行参数

直接在Claude Desktop配置中指定所有参数：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": [
        "ssh-agent-mcp@latest",
        "--host=192.168.1.100",
        "--port=22",
        "--user=root",
        "--password=your_password",
        "--timeout=30000",
        "--max-chars=none"
      ]
    }
  }
}

方式三：命令行 + 配置文件

结合配置文件和命令行参数：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": [
        "ssh-agent-mcp@latest",
        "--config=/path/to/ssh_config.json",
        "--connection=production-server"
      ]
    }
  }
}

方式三：使用私钥认证

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": [
        "ssh-agent-mcp@latest",
        "--host=prod.example.com",
        "--user=admin",
        "--key=/home/user/.ssh/id_rsa",
        "--key-password=private_key_password"
      ]
    }
  }
}

方式四：配置文件模式

使用配置文件管理多个连接：

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": [
        "ssh-agent-mcp@latest",
        "--config=/path/to/ssh_config.json",
        "--connection=production-server"
      ]
    }
  }
}

🔧 命令行参数

参数	描述	必需	示例
`--host`	SSH服务器地址	否*	`192.168.1.100`
`--user`, `--username`	SSH用户名	否*	`root`
`--port`	SSH端口	否	`22` (默认)
`--password`	SSH密码	否	`your_password`
`--key`, `--private-key`	私钥文件路径	否	`/home/user/.ssh/id_rsa`
`--key-password`, `--private-key-password`	私钥密码	否	`key_password`
`--config`, `-c`	配置文件路径	否	`/path/to/config.json`
`--connection`	配置文件中的连接名称	否	`production-server`
`--timeout`	命令超时时间（毫秒）	否	`30000` (默认)
`--max-chars`	最大输出字符数	否	`none` (默认)
`--log-level`	日志级别	否	`INFO` (默认)
`--auto-connect`	启动时自动连接	否	-

注意：

* 标记的参数在使用配置文件或无参数启动模式时不是必需的
无参数启动时，所有连接参数都是可选的，MCP服务将等待大模型通过工具提供连接信息

📋 配置文件格式

当使用配置文件时，ssh_config.json 格式如下：

{
  "connections": [
    {
      "name": "production-server",
      "host": "prod.example.com",
      "username": "admin",
      "port": 22,
      "private_key": "/home/user/.ssh/id_rsa",
      "description": "生产环境服务器",
      "tags": ["production", "critical"]
    },
    {
      "name": "dev-server",
      "host": "192.168.1.100",
      "username": "dev",
      "port": 22,
      "password": "dev_password",
      "description": "开发环境服务器",
      "tags": ["development", "test"]
    }
  ],
  "default_timeout": 30,
  "log_level": "INFO",
  "auto_connect": ["production-server"],
  "max_connections": 10
}

🛠️ MCP工具接口

该服务提供以下MCP工具：

基础连接工具

1. ssh_connect_by_name ⭐ 推荐

使用配置文件中的连接名称建立SSH连接

参数:
- connection_name (必需): 配置文件中的连接名称
示例:

{
  "name": "ssh_connect_by_name",
  "arguments": {
    "connection_name": "production-server"
  }
}

2. ssh_connect

手动建立SSH连接（不推荐，建议使用配置文件）

参数:
- host (必需): SSH服务器主机名或IP地址
- username (必需): SSH用户名
- port (可选): SSH端口，默认为22
- password (可选): SSH密码
- private_key (可选): 私钥文件路径
- private_key_password (可选): 私钥密码

3. ssh_disconnect

断开SSH连接

参数:
- connection_id (必需): SSH连接ID

4. ssh_disconnect_all

断开所有SSH连接

参数: 无

配置管理工具

5. ssh_list_config ⭐ 新功能

列出配置文件中的所有SSH连接

参数:
- filter_tag (可选): 按标签过滤连接
示例:

{
  "name": "ssh_list_config",
  "arguments": {
    "filter_tag": "production"
  }
}

6. ssh_auto_connect ⭐ 新功能

自动连接配置文件中标记为auto_connect的连接

参数: 无

状态查询工具

7. ssh_status

查询SSH连接状态

参数:
- connection_id (可选): SSH连接ID，不提供则返回所有连接状态

8. ssh_list_connections

列出所有SSH连接

参数: 无

命令执行工具

9. ssh_execute

在SSH连接上执行命令

参数:
- connection_id (必需): SSH连接ID
- command (必需): 要执行的命令
- timeout (可选): 命令超时时间（秒），默认为30

异步命令工具

10. ssh_start_async_command

启动长时间运行的异步命令

参数:
- connection_id (必需): SSH连接ID
- command (必需): 要执行的长时间运行命令

11. ssh_get_command_status

获取异步命令状态和最新输出

参数:
- command_id (必需): 异步命令ID

12. ssh_list_async_commands

列出所有异步命令状态

参数: 无

13. ssh_terminate_command

终止正在运行的异步命令

参数:
- command_id (必需): 要终止的异步命令ID

14. ssh_cleanup_commands

清理已完成的异步命令

参数:
- max_age (可选): 保留时间（秒），默认3600秒

交互式命令工具 🎮 新功能

15. ssh_start_interactive

启动交互式命令会话，支持需要用户输入的命令

参数:
- connection_id (必需): SSH连接ID
- command (必需): 要执行的交互式命令
- pty_width (可选): 伪终端宽度，默认80
- pty_height (可选): 伪终端高度，默认24
示例:

{
  "name": "ssh_start_interactive",
  "arguments": {
    "connection_id": "user@server:22",
    "command": "sudo -i",
    "pty_width": 120,
    "pty_height": 30
  }
}

16. ssh_send_input

向交互式会话发送输入

参数:
- session_id (必需): 交互式会话ID
- input_text (必需): 要发送的输入内容
示例:

{
  "name": "ssh_send_input",
  "arguments": {
    "session_id": "session-uuid",
    "input_text": "password123\n"
  }
}

17. ssh_get_interactive_output

获取交互式会话的输出

参数:
- session_id (必需): 交互式会话ID
- max_lines (可选): 最大输出行数，默认100
示例:

{
  "name": "ssh_get_interactive_output",
  "arguments": {
    "session_id": "session-uuid",
    "max_lines": 50
  }
}

18. ssh_list_interactive_sessions

列出指定连接的所有交互式会话

参数:
- connection_id (可选): SSH连接ID，不提供则返回所有连接的会话
示例:

{
  "name": "ssh_list_interactive_sessions",
  "arguments": {
    "connection_id": "user@server:22"
  }
}

19. ssh_terminate_interactive

终止交互式会话

参数:
- session_id (必需): 交互式会话ID
示例:

{
  "name": "ssh_terminate_interactive",
  "arguments": {
    "session_id": "session-uuid"
  }
}

20. ssh_connect_by_config_host ⭐ 新功能

使用SSH config文件中的主机名建立连接

参数:
- config_host (必需): SSH config文件中的主机名
- username (可选): 可选用户名，覆盖config中的设置
- password (可选): 可选密码
- private_key (可选): 可选私钥文件路径
- private_key_password (可选): 可选私钥密码
示例:

{
  "name": "ssh_connect_by_config_host",
  "arguments": {
    "config_host": "my-server"
  }
}

优势：

🎯 简化配置：直接使用~/.ssh/config中已配置的主机
🔗 自动解析：SSH客户端自动处理主机名、端口、用户等配置
🛡️ 安全性：利用SSH config的现有安全配置
📦 零配置：无需额外配置文件，直接使用标准SSH配置

📁 SFTP文件传输工具 ⭐ 新功能

21. ssh_upload_file

上传文件到远程服务器

参数:
- connection_id (必需): SSH连接ID
- local_path (必需): 本地文件路径
- remote_path (必需): 远程文件路径
示例:

{
  "name": "ssh_upload_file",
  "arguments": {
    "connection_id": "connection-uuid",
    "local_path": "/path/to/local/file.txt",
    "remote_path": "/remote/path/file.txt"
  }
}

22. ssh_download_file

从远程服务器下载文件

参数:
- connection_id (必需): SSH连接ID
- remote_path (必需): 远程文件路径
- local_path (必需): 本地文件路径
示例:

{
  "name": "ssh_download_file",
  "arguments": {
    "connection_id": "connection-uuid",
    "remote_path": "/remote/path/file.txt",
    "local_path": "/path/to/local/downloaded_file.txt"
  }
}

23. ssh_list_remote_directory

列出远程目录内容

参数:
- connection_id (必需): SSH连接ID
- remote_path (可选): 远程目录路径，默认为当前目录
示例:

{
  "name": "ssh_list_remote_directory",
  "arguments": {
    "connection_id": "connection-uuid",
    "remote_path": "/home/user/documents"
  }
}

24. ssh_create_remote_directory

在远程服务器上创建目录

参数:
- connection_id (必需): SSH连接ID
- remote_path (必需): 要创建的远程目录路径
- mode (可选): 目录权限，默认为755
- parents (可选): 是否递归创建父目录，默认为true
示例:

{
  "name": "ssh_create_remote_directory",
  "arguments": {
    "connection_id": "connection-uuid",
    "remote_path": "/remote/new/directory",
    "mode": 755,
    "parents": true
  }
}

25. ssh_remove_remote_file

删除远程文件或目录

参数:
- connection_id (必需): SSH连接ID
- remote_path (必需): 要删除的远程文件或目录路径
示例:

{
  "name": "ssh_remove_remote_file",
  "arguments": {
    "connection_id": "connection-uuid",
    "remote_path": "/remote/path/to/delete"
  }
}

26. ssh_get_remote_file_info

获取远程文件或目录信息

参数:
- connection_id (必需): SSH连接ID
- remote_path (必需): 远程文件或目录路径
示例:

{
  "name": "ssh_get_remote_file_info",
  "arguments": {
    "connection_id": "connection-uuid",
    "remote_path": "/remote/path/file.txt"
  }
}

27. ssh_rename_remote_path

重命名远程文件或目录

参数:
- connection_id (必需): SSH连接ID
- old_path (必需): 原始路径
- new_path (必需): 新路径
示例:

{
  "name": "ssh_rename_remote_path",
  "arguments": {
    "connection_id": "connection-uuid",
    "old_path": "/remote/old_name.txt",
    "new_path": "/remote/new_name.txt"
  }
}

📖 使用示例

启动MCP服务

python main.py

🌟 无参数启动工作流程（推荐）

适用场景：动态连接管理，多服务器操作，安全性要求高的环境

手动建立连接:

{
  "name": "ssh_connect",
  "arguments": {
    "host": "192.168.1.100",
    "username": "admin",
    "password": "secure_password"
  }
}

查看连接状态:

{
  "name": "ssh_list_connections",
  "arguments": {}
}

执行命令:

{
  "name": "ssh_execute",
  "arguments": {
    "connection_id": "admin@192.168.1.100:22",
    "command": "systemctl status nginx"
  }
}

连接其他服务器:

{
  "name": "ssh_connect",
  "arguments": {
    "host": "prod.example.com",
    "username": "root",
    "private_key": "/home/user/.ssh/id_rsa"
  }
}

🎯 配置文件工作流程

适用场景：固定服务器环境，批量操作，团队协作

查看配置的连接:

{
  "name": "ssh_list_config",
  "arguments": {}
}

通过名称建立连接:

{
  "name": "ssh_connect_by_name",
  "arguments": {
    "connection_name": "production-server"
  }
}

执行命令:

{
  "name": "ssh_execute",
  "arguments": {
    "connection_id": "admin@prod.example.com:22",
    "command": "df -h"
  }
}

断开连接:

{
  "name": "ssh_disconnect",
  "arguments": {
    "connection_id": "admin@prod.example.com:22"
  }
}

🏠 SSH Config工作流程 ⭐ 新功能

适用场景：已有SSH config配置，利用标准SSH配置文件

假设你的 ~/.ssh/config 文件中有以下配置：

Host my-server
    HostName 192.168.1.100
    User admin
    Port 22
    IdentityFile ~/.ssh/id_rsa

Host production
    HostName prod.example.com
    User root
    Port 2222
    IdentityFile ~/.ssh/prod_key

使用SSH config主机名建立连接:

{
  "name": "ssh_connect_by_config_host",
  "arguments": {
    "config_host": "my-server"
  }
}

覆盖config中的用户名:

{
  "name": "ssh_connect_by_config_host",
  "arguments": {
    "config_host": "production",
    "username": "deploy"
  }
}

使用密码覆盖config中的私钥认证:

{
  "name": "ssh_connect_by_config_host",
  "arguments": {
    "config_host": "my-server",
    "password": "temporary_password"
  }
}

查看连接状态:

{
  "name": "ssh_status",
  "arguments": {}
}

执行命令:

{
  "name": "ssh_execute",
  "arguments": {
    "connection_id": "my-server",
    "command": "hostname"
  }
}

优势：

🎯 零配置：直接使用已有的SSH config配置
🔗 自动解析：自动处理主机名、端口、用户名、私钥等
🛡️ 安全性：利用SSH config的现有安全设置
📦 标准化：遵循SSH标准配置约定

🚀 自动连接工作流程

启动时自动连接所有标记的服务器:

{
  "name": "ssh_auto_connect",
  "arguments": {}
}

查看所有连接状态:

{
  "name": "ssh_status",
  "arguments": {}
}

🔄 异步命令工作流程

启动长时间运行命令:

{
  "name": "ssh_start_async_command",
  "arguments": {
    "connection_id": "admin@prod.example.com:22",
    "command": "tail -f /var/log/nginx/access.log"
  }
}

查询命令状态和输出:

{
  "name": "ssh_get_command_status",
  "arguments": {
    "command_id": "返回的命令UUID"
  }
}

终止长时间运行命令:

{
  "name": "ssh_terminate_command",
  "arguments": {
    "command_id": "要终止的命令UUID"
  }
}

🎮 交互式命令工作流程

交互式命令支持让大模型能够与需要用户输入的命令进行实时交互，如 sudo、vim、mysql、python 等。

基本交互式会话

启动交互式会话:

{
  "name": "ssh_start_interactive",
  "arguments": {
    "connection_id": "admin@prod.example.com:22",
    "command": "bash",
    "pty_width": 80,
    "pty_height": 24
  }
}

发送命令到会话:

{
  "name": "ssh_send_input",
  "arguments": {
    "session_id": "返回的会话UUID",
    "input_text": "ls -la\n"
  }
}

获取会话输出:

{
  "name": "ssh_get_interactive_output",
  "arguments": {
    "session_id": "会话UUID",
    "max_lines": 50
  }
}

终止交互式会话:

{
  "name": "ssh_terminate_interactive",
  "arguments": {
    "session_id": "会话UUID"
  }
}

高级交互式场景

1. sudo 命令交互:

// 启动交互式会话
{
  "name": "ssh_start_interactive",
  "arguments": {
    "connection_id": "user@server:22",
    "command": "sudo -i"
  }
}

// 发送密码
{
  "name": "ssh_send_input",
  "arguments": {
    "session_id": "session_uuid",
    "input_text": "your_password\n"
  }
}

// 执行管理员命令
{
  "name": "ssh_send_input",
  "arguments": {
    "session_id": "session_uuid",
    "input_text": "systemctl status nginx\n"
  }
}

2. Python 交互式环境:

// 启动Python解释器
{
  "name": "ssh_start_interactive",
  "arguments": {
    "connection_id": "dev@server:22",
    "command": "python3"
  }
}

// 执行Python代码
{
  "name": "ssh_send_input",
  "arguments": {
    "session_id": "session_uuid",
    "input_text": "import os\nprint(os.getcwd())\n"
  }
}

3. 文本编辑器 (vim/nano):

// 启动vim编辑器
{
  "name": "ssh_start_interactive",
  "arguments": {
    "connection_id": "user@server:22",
    "command": "vim /etc/hosts",
    "pty_width": 120,
    "pty_height": 30
  }
}

// 进入插入模式
{
  "name": "ssh_send_input",
  "arguments": {
    "session_id": "session_uuid",
    "input_text": "i"
  }
}

// 输入内容
{
  "name": "ssh_send_input",
  "arguments": {
    "session_id": "session_uuid",
    "input_text": "127.0.0.1 localhost\n"
  }
}

// 保存并退出
{
  "name": "ssh_send_input",
  "arguments": {
    "session_id": "session_uuid",
    "input_text": "\u001b:wq\n"
  }
}

4. 数据库交互 (MySQL):

// 连接MySQL
{
  "name": "ssh_start_interactive",
  "arguments": {
    "connection_id": "db@server:22",
    "command": "mysql -u root -p"
  }
}

// 输入密码
{
  "name": "ssh_send_input",
  "arguments": {
    "session_id": "session_uuid",
    "input_text": "database_password\n"
  }
}

// 执行SQL查询
{
  "name": "ssh_send_input",
  "arguments": {
    "session_id": "session_uuid",
    "input_text": "SHOW DATABASES;\n"
  }
}

交互式会话管理

查看所有活跃会话:

{
  "name": "ssh_list_interactive_sessions",
  "arguments": {
    "connection_id": "user@server:22"
  }
}

交互式命令最佳实践

PTY 尺寸设置:
- 对于文本编辑器，建议使用较大的终端尺寸 (120x30)
- 对于简单命令交互，默认尺寸 (80x24) 即可
输入格式:
- 命令结尾添加 \n 表示回车
- 特殊键使用转义序列，如 ESC 键: \u001b
- Ctrl+C: \u0003, Ctrl+D: \u0004
输出缓冲:
- 定期获取输出避免缓冲区溢出
- 使用 max_lines 参数控制输出量
- 对于大量输出，分批获取
会话清理:
- 及时终止不需要的会话
- 避免长时间保持空闲会话
- 连接断开时会自动清理相关会话
错误处理:
- 检查会话状态，处理会话异常终止
- 对于需要密码的命令，准备好凭据
- 处理命令执行超时情况

🏷️ 标签过滤示例

查看所有生产环境连接:

{
  "name": "ssh_list_config",
  "arguments": {
    "filter_tag": "production"
  }
}

查看所有开发环境连接:

{
  "name": "ssh_list_config",
  "arguments": {
    "filter_tag": "development"
  }
}

🔗 连接ID格式

连接ID格式为: username@host:port 例如: admin@prod.example.com:22

📦 打包和分发

创建分发包

# 构建所有包格式
python build.py --all

# 仅构建wheel包
python build.py --wheel

# 仅创建便携式包
python build.py --portable

便携式包使用

下载 ssh-agent-mcp-portable.zip
解压到目标目录
安装依赖: pip install -r requirements.txt
配置SSH连接: 复制并编辑 ssh_config.json
启动服务: python start_ssh_agent.py

安全注意事项

请确保SSH凭据的安全，避免在日志中暴露敏感信息
建议使用私钥认证而非密码认证
在生产环境中考虑使用SSH代理转发
定期轮换SSH密钥和密码

错误处理

服务包含完善的错误处理机制：

连接失败时会返回详细的错误信息
命令执行失败时会返回退出码和错误输出
支持连接超时和命令执行超时

测试

运行测试脚本验证功能：

基础功能测试

python simple_test.py

MCP协议测试

python test_mcp.py

交互式命令测试

# 测试SSH Manager的交互式功能
python test_interactive.py

# 测试MCP交互式工具
python test_mcp_interactive.py

📁 项目结构

sshagent/
├── main.py              # 主入口文件
├── mcp_server.py        # MCP服务器实现
├── ssh_manager.py       # SSH连接管理器
├── config_loader.py     # 配置文件加载器
├── install.py           # 安装脚本
├── build.py             # 打包脚本
├── pyproject.toml       # 项目配置
├── README.md            # 说明文档
├── simple_test.py       # 简单测试脚本
├── test_mcp.py          # MCP协议测试
├── test_interactive.py  # 交互式命令测试脚本
├── test_mcp_interactive.py # MCP交互式工具测试
└── ssh_config.json      # SSH连接配置文件（用户创建）

📚 依赖项

mcp: Model Context Protocol实现
paramiko: SSH客户端库
pydantic: 数据验证和序列化
asyncio: 异步IO支持

🔧 Claude Desktop配置

配置文件位置

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
Linux: ~/.config/claude-desktop/claude_desktop_config.json

基本配置示例

{
  "mcpServers": {
    "ssh-mcp": {
      "command": "uvx",
      "args": [
        "ssh-agent-mcp@latest",
        "--host=192.168.1.100",
        "--user=root",
        "--password=your_password"
      ]
    }
  }
}

多服务器配置

{
  "mcpServers": {
    "ssh-prod": {
      "command": "uvx",
      "args": [
        "ssh-agent-mcp@latest",
        "--config=/path/to/prod_config.json",
        "--connection=prod-server",
        "--auto-connect"
      ]
    },
    "ssh-dev": {
      "command": "uvx",
      "args": [
        "ssh-agent-mcp@latest",
        "--host=192.168.1.200",
        "--user=dev",
        "--password=dev_password"
      ]
    }
  }
}

配置说明

uvx: Python包运行器，会自动下载并运行指定版本的包
ssh-agent-mcp@latest: 使用最新版本，也可以指定具体版本如 @0.1.0
命令行参数会覆盖配置文件中的相应设置
使用 --auto-connect 可以在启动时自动建立SSH连接

📁 SFTP文件传输示例

1. 上传文件到远程服务器:

{
  "name": "ssh_upload_file",
  "arguments": {
    "connection_id": "user@server:22",
    "local_path": "/home/user/documents/report.pdf",
    "remote_path": "/remote/uploads/report.pdf"
  }
}

2. 从远程服务器下载文件:

{
  "name": "ssh_download_file",
  "arguments": {
    "connection_id": "user@server:22",
    "remote_path": "/remote/data/backup.zip",
    "local_path": "/home/user/downloads/backup.zip"
  }
}

3. 浏览远程目录:

{
  "name": "ssh_list_remote_directory",
  "arguments": {
    "connection_id": "user@server:22",
    "remote_path": "/home/user/documents"
  }
}

4. 创建远程目录:

{
  "name": "ssh_create_remote_directory",
  "arguments": {
    "connection_id": "user@server:22",
    "remote_path": "/remote/new/project",
    "mode": 755,
    "parents": true
  }
}

5. 批量文件操作工作流:

// 1. 创建远程目录
{
  "name": "ssh_create_remote_directory",
  "arguments": {
    "connection_id": "user@server:22",
    "remote_path": "/remote/backup/2024-01-15"
  }
}

// 2. 上传多个文件
{
  "name": "ssh_upload_file",
  "arguments": {
    "connection_id": "user@server:22",
    "local_path": "/home/user/data/file1.txt",
    "remote_path": "/remote/backup/2024-01-15/file1.txt"
  }
}

// 3. 列出上传的文件
{
  "name": "ssh_list_remote_directory",
  "arguments": {
    "connection_id": "user@server:22",
    "remote_path": "/remote/backup/2024-01-15"
  }
}

6. 远程文件管理:

// 获取文件信息
{
  "name": "ssh_get_remote_file_info",
  "arguments": {
    "connection_id": "user@server:22",
    "remote_path": "/remote/logs/app.log"
  }
}

// 重命名文件
{
  "name": "ssh_rename_remote_path",
  "arguments": {
    "connection_id": "user@server:22",
    "old_path": "/remote/logs/app.log",
    "new_path": "/remote/logs/app_backup.log"
  }
}

// 删除旧文件
{
  "name": "ssh_remove_remote_file",
  "arguments": {
    "connection_id": "user@server:22",
    "remote_path": "/remote/logs/old_app.log"
  }
}

🚨 安全注意事项

🔐 请确保SSH凭据的安全，避免在日志中暴露敏感信息
🔑 建议使用私钥认证而非密码认证
🛡️ 在生产环境中考虑使用SSH代理转发
🔄 定期轮换SSH密钥和密码
📝 不要将包含密码的配置文件提交到版本控制系统

🐛 故障排除

常见问题

连接失败
- 检查SSH服务器地址和端口
- 验证用户名和密码/私钥
- 确认SSH服务正在运行
私钥认证失败
- 检查私钥文件路径
- 确认私钥权限正确（600）
- 如果私钥有密码，请提供private_key_password
配置文件错误
- 验证JSON格式是否正确
- 检查必需字段是否填写
- 查看日志获取详细错误信息
MCP服务器无法启动
- 检查Python环境和依赖
- 确认配置文件路径正确
- 查看错误日志

调试模式

设置环境变量启用调试日志：

export SSH_LOG_LEVEL=DEBUG
python main.py

🤝 贡献

欢迎提交Issue和Pull Request！

📄 许可证

MIT License

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

0.3.3

Oct 27, 2025

0.3.2

Oct 26, 2025

0.3.1

Oct 25, 2025

This version

0.3.0

Oct 25, 2025

0.2.3

Oct 24, 2025

0.2.2

Oct 24, 2025

0.2.1

Oct 24, 2025

0.1.3

Oct 24, 2025

0.1.2

Oct 24, 2025

0.1.1

Oct 24, 2025

0.1.0

Oct 24, 2025

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

ssh_agent_mcp-0.3.0-py3-none-any.whl (32.1 kB view details)

Uploaded Oct 25, 2025 Python 3

File details

Details for the file ssh_agent_mcp-0.3.0-py3-none-any.whl.

File metadata

Download URL: ssh_agent_mcp-0.3.0-py3-none-any.whl
Upload date: Oct 25, 2025
Size: 32.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.3

File hashes

Hashes for ssh_agent_mcp-0.3.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`00e6219a89299df86c99b799cab97dc3aa538e1cf08c72d0ef74772d29a299dc`
MD5	`b5d41b9f8b8d32c0ba7dfb094cee2ae4`
BLAKE2b-256	`43c27c6dffd9b9992d40bb187bb293cb317c1b70544f25b2c6ff7a1ab078657d`

See more details on using hashes here.

ssh_agent_mcp 0.3.0

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

SSH Agent MCP 服务

功能特性

🚀 快速开始

方法一：uvx 一键运行（推荐）

方法二：本地安装

方法三：使用配置文件

📝 使用方式

方式一：无参数启动（推荐）⭐

方式二：纯命令行参数

方式三：命令行 + 配置文件

方式三：使用私钥认证

方式四：配置文件模式

🔧 命令行参数

📋 配置文件格式

🛠️ MCP工具接口

基础连接工具

1. ssh_connect_by_name ⭐ 推荐

2. ssh_connect

3. ssh_disconnect

4. ssh_disconnect_all

配置管理工具

5. ssh_list_config ⭐ 新功能

6. ssh_auto_connect ⭐ 新功能

状态查询工具

7. ssh_status

8. ssh_list_connections

命令执行工具

9. ssh_execute

异步命令工具

10. ssh_start_async_command

11. ssh_get_command_status

12. ssh_list_async_commands

13. ssh_terminate_command

14. ssh_cleanup_commands

交互式命令工具 🎮 新功能

15. ssh_start_interactive

16. ssh_send_input

17. ssh_get_interactive_output

18. ssh_list_interactive_sessions

19. ssh_terminate_interactive

20. ssh_connect_by_config_host ⭐ 新功能

📁 SFTP文件传输工具 ⭐ 新功能

21. ssh_upload_file

22. ssh_download_file

23. ssh_list_remote_directory

24. ssh_create_remote_directory

25. ssh_remove_remote_file

26. ssh_get_remote_file_info

27. ssh_rename_remote_path

📖 使用示例

启动MCP服务

🌟 无参数启动工作流程（推荐）

🎯 配置文件工作流程

🏠 SSH Config工作流程 ⭐ 新功能

🚀 自动连接工作流程

🔄 异步命令工作流程

🎮 交互式命令工作流程

基本交互式会话

高级交互式场景

交互式会话管理

交互式命令最佳实践

🏷️ 标签过滤示例

🔗 连接ID格式

📦 打包和分发

创建分发包

便携式包使用

安全注意事项

错误处理

测试

基础功能测试

MCP协议测试