SSH MCP 서버 (paramiko)

Paramiko 기반 SSH MCP 서버로, 원격 머신에서 명령을 실행하고 SFTP를 통해 파일을 이동할 수 있습니다. 환경 변수 / 스위치로 선택할 수 있는 두 가지 transport 방식으로 제공됩니다:

• http – /mcp 경로의 MCP streamable-http 엔드포인트 (Cherry Studio가 등록됨), 그리고 문서화된 OpenAPI/Swagger 인터페이스 (/docs, /openapi.json).

• stdio – 고전적인 MCP stdio transport (로컬 실행 / docker exec용).

포트에 대한 중요한 사항: 2222은 Cherry Studio가 연결하는 MCP 서버의 포트입니다. 이것은 원격 머신의 SSH 포트가 아닙니다! 원격 머신의 SSH 포트는 일반적으로 22(SSH_PORT)입니다. 즉: Cherry Studio → http://<host-IP>:2222/mcp → MCP 서버 → paramiko → 원격 머신의 22 SSH 포트.

사용 가능한 MCP 도구

상태 비저장(stateless) 도구 — 간단하고 일회성 작업

상태 저장(stateful) 대화형 세션 도구 — 살아 있는 셸

이들은 살아 있는 셸을 열어두고, 호출 사이에도 상태가 유지됩니다 (cd 이후 디렉터리 변경, export된 변수, 대화형 프롬프트 처리: sudo 비밀번호, apt [Y/n] 등).

도구 설명(docstring)은 의도적으로 매우 상세하면서도 간단한 영어 "USE THIS WHEN..." 가이드를 포함하고 있어, 소비 모델이 각 도구를 언제 그리고 어떻게 사용하는지 분명하게 알 수 있습니다.

모든 도구 파라미터 (host, port, username, password, private_key, private_key_path, passphrase, timeout)는 다음 중 하나로 지정할 수 있습니다:

• 호출마다 개별적으로, 또는

• 기본값으로 .env 파일에서 (SSH_* 변수). 호출에서 지정되지 않은 것은 시스템이 SSH_* 환경변수에서 가져옵니다.

지원 인증: 비밀번호 및 키 (인라인 PEM 또는 파일 경로, 선택적으로 비밀번호). 알 수없는 호스트 키는 서버가 자동으로 수용합니다 (AutoAddPolicy), 그래서 자동화가 매끄럽게 동작합니다.

Related MCP server: SSH MCP Server

상태 비저장(stateless) vs. 상태 유지(stateful, interactive) 사용

언제 어떤 것을?

• 하나의 독립적인 명령 (예: ls, uptime, df -h) → ssh_execute. 호출마다 새 연결을 열고, 명령 하나를 실행한 다음 닫습니다. 메모리가 없습니다: cd와 export는 다음 호출까지 유지되지 않으며, 대화형 프롬프트에 응답할 수 없습니다.

• 대화형이거나 여러 단계가 필요한 경우 (cd/export 후 상태 유지, sudo 비밀번호 입력, apt [Y/n] 응답, 단계에 이어지는 명령) → 대화형 세션: ssh_open_session → ssh_send → ssh_read → ssh_close_session.

권장 워크플로우 (세션)

1. ssh_open_session → session_id를 받습니다 (입력 배너 / 첫 프롬프트는 initial_output에 포함).

2. ssh_send → 명령을 입력하거나 프롬프트에 응답합니다. session_id는 session_id를 반드시 전달해야 합니다. 기본적으로 Enter을 보냅니다.

3. ssh_read (선택) → 느리거나 오래 걸리는 명령에서 전송 없이 추가 출력을 수집합니다.

4. ssh_close_session → 모든 작업이 끝나면 세션을 닫습니다.

ssh_list_sessions로 언제든 열린 세션 (host, 사용자, 유휴 상태)을 확인할 수 있으며, 이때 session_id를 잃어버린 경우에도 확인할 수 있습니다.

예시 (REST 엔드포인트 이용)

세션 열기:

curl -X POST http://localhost:2222/api/ssh/session/open \
  -H "Content-Type: application/json" \
  -d '{"host":"192.168.1.100","username":"user","password":"secret"}'
# -> {"ok":true,"session_id":"<ID>", "initial_output":"...prompt..."}

디렉터리 변경 유지 (상태 저장):

curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"cd /var/log && pwd"}'
# a következő ssh_send már a /var/log-ban futna

sudo 명령 + 비밀번호 프롬프트 응답:

# 1) elindítod a sudo parancsot
curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"sudo apt-get update"}'
# 2) a kimenetben megjelenik a "[sudo] password for user:" prompt -> beküldöd a jelszót
curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"my_sudo_password"}'

apt [Y/n] 질문에 응답:

curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"sudo apt-get install htop","read_timeout":5}'
# amikor jön a "Do you want to continue? [Y/n]" kérdés:
curl -X POST http://localhost:2222/api/ssh/session/send \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>","input":"Y"}'

세션 닫기:

curl -X POST http://localhost:2222/api/ssh/session/close \
  -H "Content-Type: application/json" \
  -d '{"session_id":"<ID>"}'

타임아웃 / 유휴 / 오류: 모든 세션 조작은 SSH_SESSION_IDLE_TIMEOUT(기본 600초) 보다 오래 유휴된 세션, 그리고 채널이 끊어진 세션을 자동으로 닫습니다. 동시에 최대 SSH_MAX_SESSIONS(기본 20개) 개의 세션을 동시에 열 수 있고, 한도에 도달하면 명확한 오류 메시지를 반환합니다. 어떤 session_id가 더 이상 존재하지 않으면, 응답은 정확히 무엇을 해야 하는지 (새 세션을 열거나 ssh_list_sessions 확인) 알려줍니다.

프로젝트 구조

ssh-mcp-server/
├── app/
│   ├── __init__.py
│   ├── ssh_ops.py     # paramiko SSH/SFTP műveletek (közös logika)
│   └── server.py      # MCP tool-ok + FastAPI/OpenAPI + transport választás
├── requirements.txt
├── Dockerfile
├── docker-compose.yml # 2222:2222 publikálás
├── .env.example
└── README.md

1. Docker로 빠른 시작 (권장)

준비

cd ssh-mcp-server
cp .env.example .env
# szerkeszd a .env-et: add meg a távoli gép adatait (SSH_HOST, SSH_USERNAME, stb.)

빌드 및 실행 (HTTP 모드)

docker compose up -d --build

이 방법으로 서버를 HTTP 모드로 시작하고, 2222 포트를 호스트에 출판합니다 (ports: "2222:2222").

확인

curl http://localhost:2222/health
# {"status":"ok","service":"ssh-mcp-server","mcp_endpoint":"/mcp"}

• Swagger UI (브라우저): http://localhost:2222/docs

• OpenAPI JSON: http://localhost:2222/openapi.json

• MCP 엔드포인트 (Cherry Studio): http://<host-IP>:2222/mcp

중지

docker compose down

2. HTTP 모드 수동 실행 (Docker 없이, 개발용)

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export TRANSPORT=http HOST=0.0.0.0 PORT=2222
python -m app.server

3. stdio 모드

컨테이너에서 실행 중인 서버일 경우 docker exec로:

docker exec -i -e TRANSPORT=stdio ssh-mcp-server python -m app.server

또는 Docker 없이 직접 실행:

TRANSPORT=stdio python -m app.server

4. Cherry Studio 통합

A) HTTP (streamable-http) 모드 – 권장, 네트워크를 통해 작동

컨테이너가 노트북의 Docker에서 실행되고, Cherry Studio는 호스트 IP와 2222 포트를 사용합니다.

1. 서버를 시작한다: docker compose up -d --build

2. Docker가 실행되는 컴퓨터(호스트)의 IP 주소를 확인한다:

   • Linux: hostname -I → 예: 192.168.1.50

   • Cherry Studio가 동일한 컴퓨터에서 실행되고 있다면 localhost / 127.0.0.1도 사용 가능.

3. Cherry Studio → 설정 (Settings) → MCP Servers → Add / 새 서버.

4. 다음을 설정한다:

   • Type / Típus: Streamable HTTP (없으면 SSE/HTTP`)

   • URL / 엔드포인트: http://<host-IP>:2222/mcp

     • 예: http://192.168.1.50:2222/mcp

     • 원격이면: http://localhost:2222/mcp

5. 저장하고 활성화(Enable) 한다. Cherry Studio가 ssh_test, ssh_execute, ssh_upload, ssh_download 도구들을 로드합니다.

원격 컴퓨터에서 연결하는 경우, 2222 포트에 접근 가능하지(방화벽 허용) 확인하고, Docker가 0.0.0.0으로 바인딩하고 있는지(기본적으로) 확인하세요.

B) stdio 모드

Cherry Studio가 stdio MCP 서버(명령을 실행)를 기대하는 경우:

• Command: docker

• Arguments:

  exec -i -e TRANSPORT=stdio ssh-mcp-server python -m app.server

(위한 ssh-mcp-server 컨테이너가 실행 중이어야 합니다 — docker compose up -d.)

5. .env 설정

Docker에서 키 인증

키를 컨테이너에 마운트하고 경로를 설정합니다. docker-compose.yml에서 volumes 줄의 주석을 제거합니다:

    volumes:
      - ./keys:/keys:ro

그 다음 .env에:

SSH_PRIVATE_KEY_PATH=/keys/id_ed25519

6. 테스트 REST 엔드포인트 (OpenAPI)

HTTP 형식은 Cherry Studio MCP 엔드포인트 옆에 REST 엔드포인트를 제공합니다 — 동일한 SSH 작업을 수행하며 curl / Swagger UI에서 사용하기 쉽습니다:

예제 (상태 저장되지 않은 단일 명령):

curl -X POST http://localhost:2222/api/ssh/execute \
  -H "Content-Type: application/json" \
  -d '{"host":"192.168.1.100","username":"user","password":"secret","command":"uname -a"}'

리피코어 노트

• 코드에는 비밀이 절대 없다 — 모든 것을 .env 또는 호출 매개변수에서 읽습니다.

• .env 파일은 .dockerignore 및 일반적으로 .gitignore가 배제할 수 있습니다 — 버전 관리에 커밋하지 마세요.

• 서버는 AutoAddPolicy를 사용합니다(알 수 없는 호스트 키 자동 수락). 폐쇄 네트워크에서는 편리; 엄격한 환경에서는 알려진 호스트 키를 사용하는 것이 좋습니다.

• 2222 MCP 포트는 신뢰할 수 있는 네트워크에서만 접근을 허용하세요.