SSH MCP Szerver (paramiko)

Paramiko-alapú SSH MCP szerver, amely távoli gépeken tud parancsot futtatni és fájlokat mozgatni SFTP-n keresztül. Kétféle transporton érhető el, ami környezeti változóval / kapcsolóval választható:

• http – MCP streamable-http végpont a /mcp útvonalon (ide csatlakozik a Cherry Studio), plusz dokumentált OpenAPI/Swagger felület (/docs, /openapi.json).
• stdio – klasszikus MCP stdio transport (helyi indításhoz / docker exec-hez).

FONTOS a portokról: a 2222 az az MCP szerver portja, ahová a Cherry Studio csatlakozik. Ez NEM a távoli gép SSH portja! A távoli gép SSH portja általában a 22 (SSH_PORT). Tehát: Cherry Studio → http://<host-IP>:2222/mcp → MCP szerver → paramiko → távoli gép 22-es SSH portja.

---

Elérhető MCP tool-ok

Állapotmentes (stateless) eszközök — egyszerű, egyszeri műveletek

Tool	Leírás
ssh_test	Kapcsolat és hitelesítés tesztelése egy távoli géppel.
ssh_execute	EGYETLEN shell parancs futtatása friss kapcsolatban (stdout / stderr / exit kód). Nincs memória: a cd / export nem öröklődik a következő hívásra, és nem tud interaktív promptra válaszolni.
ssh_upload	Helyi fájl feltöltése a távoli gépre SFTP-vel.
ssh_download	Fájl letöltése a távoli gépről SFTP-vel.

Állapottartó (stateful), interaktív session eszközök — élő shell

Ezek egy élő shellt tartanak nyitva, ahol az állapot megmarad hívások között (könyvtárváltás cd után, export-ált változók, interaktív promptok kezelése: sudo jelszó, apt [Y/n] stb.).

Tool	Leírás
ssh_open_session	1. lépés – új interaktív shell nyitása, visszaad egy session_id-t.
ssh_send	2. lépés – szöveg (parancs vagy prompt-válasz) küldése a session-be. A session_id-t mindig át kell adni.
ssh_read	3. lépés (opcionális) – további kimenet beolvasása küldés nélkül (lassú/hosszú parancsokhoz).
ssh_close_session	4. lépés – a session lezárása. Mindig zárd le, ha végeztél.
ssh_list_sessions	A nyitott session-ök listázása (host, felhasználó, tétlenség), pl. ha elveszett a session_id.

A tool-leírások (docstringek) szándékosan nagyon részletes, egyszerű angol nyelvű "USE THIS WHEN..." útmutatót tartalmaznak, hogy a fogyasztó modell egyértelműen tudja, mikor és hogyan használja az egyes eszközöket.

Minden tool paraméterei (host, port, username, password, private_key, private_key_path, passphrase, timeout) megadhatók:

• hívásonként külön-külön, vagy
• alapértelmezettként a .env fájlban (SSH_* változók). Ami a hívásban nincs megadva, azt a rendszer az SSH_* környezeti változókból veszi.

Támogatott hitelesítés: jelszó és kulcs (inline PEM vagy fájlútvonal, opcionális jelszóval). Az ismeretlen host kulcsokat a szerver automatikusan elfogadja (AutoAddPolicy), hogy az automatizálás gördülékeny legyen.

---

Állapotmentes vs. állapottartó (interaktív) használat

Melyiket mikor?

• Egyetlen, önálló parancs (pl. ls, uptime, df -h) → ssh_execute. Minden hívás friss kapcsolatot nyit, lefuttat egy parancsot, majd bezár. Nincs memória: a cd és export nem él túl a következő hívásig, és interaktív promptra sem tud válaszolni.
• Bármi interaktív vagy több lépéses (állapotmegőrzés cd/export után, sudo jelszó megadása, apt [Y/n] megválaszolása, egymásra épülő parancsok) → interaktív session: ssh_open_session → ssh_send → ssh_read → ssh_close_session.

Ajánlott munkafolyamat (session)

1. ssh_open_session → visszakapsz egy session_id-t (és a belépési bannert / első promptot az initial_output-ban).
2. ssh_send → parancsot gépelsz be vagy promptra válaszolsz. A session_id-t minden híváskor át kell adni. Alapból Entert is küld.
3. ssh_read (opcionális) → lassú/hosszan futó parancsnál további kimenet begyűjtése küldés nélkül.
4. ssh_close_session → ha végeztél, zárd le a session-t.

ssh_list_sessions-nel bármikor megnézheted a nyitott session-öket (host, felhasználó, tétlenség), ha elveszett egy session_id.

Példák (REST végpontokon keresztül)

Session nyitása:

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..."}

Könyvtárváltás, ami megmarad (állapottartás):

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 parancs + jelszó-prompt megválaszolása:

# 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] kérdés megválaszolása:

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"}'

Session lezárása:

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

Időtúllépés / tétlenség / hibák: minden session-művelet opportunistán lezárja a SSH_SESSION_IDLE_TIMEOUT-nál (alap 600 mp) régebb óta tétlen session-öket, valamint azokat, amelyeknek a csatornája elhalt. Egyszerre legfeljebb SSH_MAX_SESSIONS (alap 20) session lehet nyitva — a limit elérése egyértelmű hibaüzenetet ad. Ha egy session_id már nem létezik, a válasz pontosan megmondja, mit tegyél (nyiss újat, vagy nézd meg ssh_list_sessions-nel).

---

Projekt felépítés

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. Gyors indítás Docker-rel (ajánlott)

Előkészítés

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.)

Build és indítás (HTTP mód)

docker compose up -d --build

Ez elindítja a szervert HTTP módban, és a 2222-es portot kipublikálja a hosztra (ports: "2222:2222").

Ellenőrzés

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

• Swagger UI (böngészőben): http://localhost:2222/docs
• OpenAPI JSON: http://localhost:2222/openapi.json
• MCP végpont (Cherry Studio): http://<host-IP>:2222/mcp

Leállítás

docker compose down

---

2. HTTP mód kézzel (Docker nélkül, fejlesztéshez)

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 mód

Konténerben futó szerver mellett docker exec-kel:

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

Vagy közvetlenül, Docker nélkül:

TRANSPORT=stdio python -m app.server

---

4. Cherry Studio integráció

A) HTTP (streamable-http) mód – ajánlott, hálózaton át is működik

A konténer a laptopodon fut Dockerben, a Cherry Studio pedig a host IP-jét és a 2222-es portot használja.

1. Indítsd el a szervert: docker compose up -d --build
2. Derítsd ki a gép (host) IP-címét, amin a Docker fut:
   • Linux: hostname -I → pl. 192.168.1.50
   • Ha a Cherry Studio ugyanazon a gépen fut, a localhost / 127.0.0.1 is jó.
3. Cherry Studio → Beállítások (Settings) → MCP Servers → Add / Új szerver.
4. Add meg az alábbiakat:
   • Type / Típus: Streamable HTTP (ha nincs, akkor SSE / HTTP)
   • URL / Endpoint: http://<host-IP>:2222/mcp
     • pl. http://192.168.1.50:2222/mcp
     • ugyanazon a gépen: http://localhost:2222/mcp
5. Mentsd el és engedélyezd (Enable) a szervert. A Cherry Studio betölti a ssh_test, ssh_execute, ssh_upload, ssh_download tool-okat.

Ha távoli gépről csatlakozol, győződj meg róla, hogy a 2222-es port elérhető (tűzfal engedélyezze), és a Docker a 0.0.0.0-ra hallgat (alapból így van).

B) stdio mód

Ha a Cherry Studio stdio MCP szervert vár (parancsot indít):

• Command: docker
• Arguments:

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

(Ehhez a ssh-mcp-server konténernek futnia kell — docker compose up -d.)

---

5. .env konfiguráció

Változó	Leírás	Alapértelmezés
TRANSPORT	http vagy stdio	http
HOST	MCP HTTP bind cím	0.0.0.0
PORT	MCP HTTP port (amit a Cherry Studio elér)	2222
SSH_HOST	Távoli gép címe	–
SSH_PORT	Távoli gép SSH portja	22
SSH_USERNAME	SSH felhasználó	–
SSH_PASSWORD	SSH jelszó (vagy használj kulcsot)	–
SSH_PRIVATE_KEY	Inline privát kulcs (PEM)	–
SSH_PRIVATE_KEY_PATH	Privát kulcs fájl útvonala (a konténerben)	–
SSH_PASSPHRASE	Privát kulcs jelszava	–
SSH_TIMEOUT	Kapcsolat timeout (mp)	15
SSH_SESSION_IDLE_TIMEOUT	Tétlen interaktív session automatikus lezárása ennyi mp után (0 = nincs)	600
SSH_MAX_SESSIONS	Egyszerre nyitható interaktív session-ök maximuma	20

Kulcsos hitelesítés Dockerben

Csatold be a kulcsokat a konténerbe, és állítsd be az útvonalat. A docker-compose.yml-ben vedd ki a kommentet a volumes sornál:

    volumes:
      - ./keys:/keys:ro

majd a .env-ben:

SSH_PRIVATE_KEY_PATH=/keys/id_ed25519

---

6. REST végpontok teszteléshez (OpenAPI)

A HTTP mód a Cherry Studio MCP végpont mellett REST végpontokat is kínál — ezek ugyanazokat az SSH műveleteket végzik, és jól használhatók curl-lel / Swagger UI-ból:

Metódus	Útvonal	Művelet
GET	/health	Állapot
GET	/	Szerver infó
POST	/api/ssh/test	Kapcsolat teszt
POST	/api/ssh/execute	Parancs futtatás
POST	/api/ssh/upload	Fájl feltöltés (SFTP)
POST	/api/ssh/download	Fájl letöltés (SFTP)
POST	/api/ssh/session/open	Interaktív session nyitása (1. lépés)
POST	/api/ssh/session/send	Bemenet küldése a session-be (2. lépés)
POST	/api/ssh/session/read	Kimenet olvasása küldés nélkül (3. lépés)
POST	/api/ssh/session/close	Session lezárása (4. lépés)
GET	/api/ssh/session/list	Nyitott session-ök listája

Példa (állapotmentes egyparancsos futtatás):

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"}'

---

Biztonsági megjegyzések

• Titkok soha nincsenek a kódban — mindent .env-ből / hívási paraméterből olvas.
• A .env fájlt a .dockerignore és jellemzően a .gitignore is kizárja — ne kommitold verziókezelőbe.
• A szerver AutoAddPolicy-t használ (ismeretlen host kulcsok automatikus elfogadása). Zárt hálózaton kényelmes; szigorúbb környezetben érdemes ismert host kulcsokat használni.
• A 2222-es MCP portot csak megbízható hálózaton tedd elérhetővé.