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

MCP server SSH/SFTP cho nhiều máy chủ Windows/Linux. Từ 0.7.0 server chỉ gồm sáu tool: chạy lệnh, tạo thư mục, liệt kê thư mục, upload/download file có xác minh SHA-256 và liệt kê server đã cấu hình. Durable job, nProx Runner, PTY và các tool SFTP legacy đã bị gỡ; xem CHANGELOG để biết cách chuyển đổi.

Verified file transfers

sftp_upload and sftp_download use configured aliases only, with no inline credentials, file content or Base64. Both return {server_name,source_path,destination_path,bytes_transferred, sha256,verification}; verification is always sha256, even without an expected digest.

Configure an absolute existing SFTP_STAGING_ROOT on the MCP host and optional per-alias allowed_transfer_roots, for example ["/srv/releases", "/srv/backups"] or ["C:/releases", "C:/backups"]. An empty list allows only canonical remote login home and its descendants, not the whole filesystem. Parents must already exist: transfers do not create directories. Paths reject traversal, symlinks, junction/reparse traversal, devices and alternate data streams. Keep these roots private to trusted transfer/service accounts; SFTP metadata does not replace filesystem ACLs or protection against another privileged writer. Legacy file tools retain their compatibility behavior and do not acquire the new remote-root policy.

SFTP_MAX_FILE_SIZE is a positive byte limit, default 2147483648 (2 GiB), checked before and during streaming and independent temporary-file readback. Source bytes are incrementally hashed; a securely named exclusive sibling temporary file is independently SHA-256 checked before atomic publication. Remote overwrite requires the server's POSIX-rename extension; there is no delete-and-rename fallback. Local no-clobber uses a same-directory hard link and requires filesystem support. Neither operation replays automatically. On uncertain disconnect/publication, inspect the destination and named .part-* sibling before deciding what to do; temporary evidence is deliberately retained. Only definite pre-publication failures clean their validated temporary file. Source files remain untouched.

Example upload:

{"local_path":"release/app.zip","remote_path":"/srv/releases/app.zip","server_name":"build","overwrite":false}

Call sftp_download with the same shape to fetch a file into staging; create the destination folder (for example logs) inside staging first. File bytes never enter MCP JSON.

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==0.7.0

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

• Multi-host: tương tác với nhiều máy chủ mà không cần chạy nhiều instance.
• Thực thi qua SSH: chạy lệnh shell trên máy chủ từ xa.
• Quản lý thư mục: tạo và liệt kê thư mục từ xa.
• Truyền file có xác minh: SFTP upload/download với SHA-256, giới hạn root và ghi nguyên tử.

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==0.7.0"
      ],
      "env": {
        "SSH_CONFIG_FILE": "C:\\Users\\NamHT\\ssh_servers.json"
      }
    }
  }
}

Lấy danh sách server từ NProx API

Khi inventory được quản lý tập trung, truyền --url-host và đặt token trong biến môi trường SSH_URL_HOST_TOKEN. URL phải là HTTPS; token không được đưa vào args, log hoặc output tool.

{
  "mcpServers": {
    "ssh-server": {
      "command": "uvx",
      "args": [
        "ssh-mcp-vn==0.7.0",
        "--url-host",
        "https://nprox.dev/api/external/devops/servers"
      ],
      "env": {
        "SSH_URL_HOST_TOKEN": "<NPROX_API_TOKEN>",
        "SSH_REMOTE_POLICY": "{\"windows-build\":{\"allowed_transfer_roots\":[\"C:/releases\"]}}"
      }
    }
  }
}

Endpoint phải trả về object có mảng servers; mỗi item cần name, host, port và username. Nếu item không có password/key_path, MCP gọi endpoint kế bên /connection?name=<URL-encoded-name> bằng cùng Bearer token và chỉ giữ credential trong process; credential không xuất hiện trong tool schema, log hoặc kết quả.

SSH_REMOTE_POLICY là object JSON theo tên server, chỉ cho phép field không chứa secret allowed_transfer_roots. Nó không thể thay host, user, port hoặc credential.

Thêm server KHÔNG dùng file JSON (nhập thẳng)

Nếu chỉ có 1 server và không muốn tạo file cấu hình hay escape chuỗi JSON, bạn có thể khai báo từng biến env riêng trong mcp_config.json:

Dạng 1 — Một server (từng biến env riêng, khuyên dùng):

{
  "mcpServers": {
    "ssh-server": {
      "command": "uvx",
      "args": [
        "ssh-mcp-vn==0.7.0"
      ],
      "env": {
        "SSH_NAME": "production",
        "SSH_HOST": "192.168.1.10",
        "SSH_USER": "ops",
        "SSH_PORT": "22",
        "SSH_KEY_PATH": "~/.ssh/toppion_ops_ed25519"
      }
    }
  }
}

Các biến hỗ trợ: SSH_NAME (bắt buộc), SSH_HOST (bắt buộc), SSH_USER, SSH_PORT (mặc định 22), SSH_KEY_PATH, SSH_PASSWORD.

Dạng 2 — Nhiều server (mảng JSON):

{
  "mcpServers": {
    "ssh-server": {
      "command": "uvx",
      "args": [
        "ssh-mcp-vn==0.7.0"
      ],
      "env": {
        "SSH_SERVERS": "[{\"name\": \"production\", \"host\": \"192.168.1.10\", \"user\": \"ops\", \"key_path\": \"~/.ssh/toppion_ops_ed25519\"}, {\"name\": \"staging\", \"host\": \"192.168.1.11\", \"user\": \"ops\", \"key_path\": \"~/.ssh/toppion_ops_ed25519\"}]"
      }
    }
  }
}

Thứ tự ưu tiên: SSH_URL_HOST > SSH_CONFIG_FILE > SSH_SERVERS > các biến SSH_NAME/SSH_HOST riêng lẻ. Nếu chỉ có 1 server, dùng Dạng 1 cho gọn, không cần escape JSON.

Hoặc chạy trực tiếp qua CLI với tham số --servers (dùng để test nhanh, hỗ trợ cả object đơn lẫn array):

uvx ssh-mcp-vn==0.7.0 --servers '{"name": "production", "host": "192.168.1.10", "user": "ops", "key_path": "~/.ssh/toppion_ops_ed25519"}' --smoke-test production

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==0.7.0 --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==0.7.0 --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)

Khi chỉ cấu hình 1 server, server_name là tùy chọn. Khi có nhiều server, server_name là bắt buộc; gọi list_ssh_servers để xem alias hợp lệ.

Mọi tool chỉ nhận configured alias qua server_name; không tool nào nhận host, user, port, password hay key_path trong lời gọi. Credential chỉ nằm trong cấu hình server.

Hướng dẫn sử dụng (Usage)

ssh_execute_command
  server_name: toppion-linux
  command: df -h

ssh_create_folder
  server_name: toppion-linux
  path: /srv/releases/2026-09

sftp_list_directory
  server_name: toppion-linux
  path: /srv/releases

{"local_path":"release/app.zip","remote_path":"/srv/releases/2026-09/app.zip","server_name":"toppion-linux"}

Gọi sftp_upload với object trên; sftp_download dùng cùng shape. Mọi input đều có mô tả, ràng buộc, giá trị mặc định và ví dụ trong JSON Schema (được tests/test_tool_schema.py kiểm tra).

Changelog

0.6.0 - 2026-09-15

New

• Thêm runner-first durable jobs, structured results, idempotent reconnect, stdin/cancel và PTY service trên Windows/Linux.
• Thêm runner health, log preview/artifacts và SFTP transfer có scope + SHA-256.

Changed

• PowerShell/pwsh job nhận script UTF-8 riêng, không đi qua raw SSH command quoting.
• runner=auto ưu tiên service; Windows fallback agentless khi detach an toàn, không replay khi mất kết nối. Linux dùng legacy synchronous tool khi chưa có runner.

0.4.0 - 2026-08-17

New

• Thêm inline connection: mọi tool nhận thêm host, user, port, password, key_path để kết nối thẳng khi chưa có credential lưu sẵn.

0.2.0 - 2026-08-10

Breaking

• Xoá tool ssh_smoke_test và ssh_smoke_test_all khỏi MCP (vẫn dùng được qua CLI --smoke-test).

Changed

• Chỉ cấu hình 1 server → server_name là tùy chọn ở mọi tool; list_ssh_servers chỉ xuất hiện khi có nhiều server.

0.1.8 - 2026-08-10

New

• SSH_SERVERS, --servers và file JSON giờ chấp nhận cả object đơn {...} lẫn array [{...}], không bắt buộc bọc mảng khi chỉ có 1 server.

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