SSH & SFTP MCP Server (ssh-mcp-vn)

Một MCP (Model Context Protocol) Server mạnh mẽ dùng để thực thi lệnh (SSH) và truyền tải file (SFTP) trên nhiều máy chủ Linux từ xa (multi-host) cùng lúc.

Hướng dẫn cài đặt

Chạy qua UVX (Được khuyến nghị)

Bạn có thể chạy trực tiếp server này qua uvx mà không cần phải tải hay cài đặt thủ công:

uvx ssh-mcp-vn

Các tính năng chính

• Hỗ trợ Multi-host: Có thể tương tác với nhiều máy chủ Linux mà không cần chạy nhiều instance.
• Thực thi qua SSH: Chạy lệnh bash/shell tùy ý trên máy chủ từ xa.
• Quản lý thư mục: Dễ dàng tạo cấu trúc thư mục từ xa (hoạt động giống lệnh mkdir -p).
• Tải lên qua SFTP: Đẩy file từ máy tính cá nhân lên máy chủ từ xa.
• Tải về qua SFTP: Tải file từ máy chủ từ xa về máy tính.
• Liệt kê file bằng SFTP: Xem danh sách các file trong một thư mục bất kỳ trên máy chủ.

Cấu hình (Khuyên dùng qua File JSON)

Vì mảng cấu hình có thể khá dài và việc viết chuỗi JSON dính liền với các dấu \ (escape) trong cấu hình môi trường sẽ phức tạp, bạn nên tách cấu hình ra một file JSON riêng biệt.

Bước 1: Tạo một file có tên ssh_servers.json ở bất kỳ đâu trên máy của bạn (ví dụ C:\Users\BiNgo\.codex\ssh_servers.json) và điền danh sách các server dạng mảng thuần túy.

Ưu tiên dùng SSH key qua key_path và user vận hành riêng có sudo. Không nên để root + password plaintext làm cấu hình mặc định.

[
  {
    "name": "toppion-linux",
    "host": "192.168.1.100",
    "user": "ops",
    "key_path": "C:\\Users\\BiNgo\\.ssh\\toppion_ops_ed25519",
    "port": 22
  },
  {
    "name": "toppion-registry",
    "host": "192.168.1.101",
    "user": "ops",
    "key_path": "C:\\Users\\BiNgo\\.ssh\\toppion_ops_ed25519"
  },
  {
    "name": "toppion-master",
    "host": "192.168.1.102",
    "user": "ops",
    "key_path": "C:\\Users\\BiNgo\\.ssh\\toppion_ops_ed25519"
  }
]

Bước 2: Cập nhật mcp_config.json của ArcticFactory chỉ truyền vào biến SSH_CONFIG_FILE trỏ đến file đó:

{
  "mcpServers": {
    "ssh-server": {
      "command": "uvx",
      "args": [
        "ssh-mcp-vn"
      ],
      "env": {
        "SSH_CONFIG_FILE": "C:\\Users\\NamHT\\ssh_servers.json"
      }
    }
  }
}

Các trường trong từng block JSON cấu hình

Mỗi object của một server hỗ trợ các trường sau:

• name (bắt buộc): Tên gọi riêng cho server này (VD: "production", "staging") để giúp công cụ AI nhận biết server muốn thao tác.
• host (bắt buộc): Địa chỉ IP hoặc Hostname của máy chủ SSH.
• user (bắt buộc): Tên đăng nhập (username).
• port (tùy chọn): Cổng SSH, mặc định là 22.
• key_path (khuyên dùng): Đường dẫn tuyệt đối đến file khóa bí mật (private key).
• password (tùy chọn, không khuyên dùng): Mật khẩu đăng nhập. Chỉ nên dùng tạm khi chưa chuyển xong sang SSH key.

Kiểm tra cấu hình và smoke test

Sau khi sửa ssh_servers.json, hãy restart/reload Codex MCP trước khi kết luận lỗi config vì MCP server đọc cấu hình khi process khởi động.

Kiểm tra config đã được đọc đúng và không in secret:

uvx ssh-mcp-vn --config-file "C:\Users\BiNgo\.codex\ssh_servers.json" --validate-config

Chạy smoke test chuẩn cho toàn bộ server:

uvx ssh-mcp-vn --config-file "C:\Users\BiNgo\.codex\ssh_servers.json" --smoke-test all

Smoke test dùng lệnh:

hostname && whoami && pwd && uptime

Nếu đang làm trực tiếp trong source repo, có thể dùng script:

python3 uvx/ssh/scripts/smoke_test.py --config-file "C:\Users\BiNgo\.codex\ssh_servers.json" --server all

Checklist vận hành ngắn:

1. Dùng alias MCP thống nhất: toppion-linux, toppion-registry, toppion-master.
2. Không phụ thuộc shell alias; MCP chỉ dùng name trong ssh_servers.json.
3. Ưu tiên key_path; hạn chế password plaintext.
4. Dùng user vận hành riêng có sudo; chỉ dùng root khi thật cần.
5. Sửa config xong thì restart/reload Codex MCP rồi chạy smoke test.

Danh sách công cụ (Tools)

(Tất cả các công cụ đều yêu cầu tham số server_name để hệ thống biết sẽ thao tác trên máy chủ nào).

• list_ssh_servers: Liệt kê server đã cấu hình với thông tin auth đã sanitize và cảnh báo vận hành.
• ssh_smoke_test: Chạy smoke test chuẩn trên một server.
• ssh_smoke_test_all: Chạy smoke test chuẩn trên toàn bộ server.
• ssh_execute_command: Chạy một lệnh shell trên máy Linux từ xa.
• ssh_create_folder: Tạo thư mục từ xa.
• sftp_upload_file: Chuyển một file từ local lên máy chủ.
• sftp_download_file: Lấy một file từ máy chủ về local.
• sftp_list_directory: Liệt kê tất cả file trong một thư mục từ xa.

Changelog

0.1.7 - 2026-08-10

Fixed

• Khóa mcp>=1.2.0,<2 để tránh uvx resolve nhầm lên mcp 2.0.0, bản này đã bỏ mcp.server.fastmcp khiến server crash với ModuleNotFoundError: No module named 'mcp.server.fastmcp'.

0.1.5 - 2026-07-05

New

• list_ssh_servers: Xem danh sách server đã cấu hình với thông tin auth đã sanitize, không in password.
• ssh_smoke_test: Kiểm tra nhanh một server bằng lệnh hostname && whoami && pwd && uptime.
• ssh_smoke_test_all: Kiểm tra nhanh toàn bộ server trong ssh_servers.json.
• CLI --validate-config: Kiểm tra config và cảnh báo vận hành mà không cần mở MCP client.

Improved

• Khuyến nghị cấu hình bằng key_path và user vận hành riêng thay vì mặc định root + password plaintext.
• Publish scripts dùng UV_PUBLISH_TOKEN thay vì lưu PyPI token trong source.
• key_path hỗ trợ ~ và biến môi trường.
• SSH command có timeout mặc định để tránh treo lâu khi server không phản hồi.

Fixed

• Sửa tương thích MCP SDK bằng cách bỏ tham số description không được hỗ trợ trong FastMCP(...).
• ssh_create_folder quote remote path trước khi chạy mkdir -p.

Xem lịch sử đầy đủ tại CHANGELOG.md.

License

MIT