mcp2term

Expose un terminal interactif via MCP (Model Context Protocol) sur Internet grâce à ngrok, pour permettre à ChatGPT, Claude Desktop ou tout client MCP d'exécuter des commandes shell à distance.

Architecture

[Client MCP] <--HTTPS--> [ngrok (Basic Auth)] <--> [FastMCP Server] <--> [Shell (cmd/bash)]

Related MCP server: Claude Desktop Commander MCP

Prérequis

• Python ≥ 3.11

ngrok est optionnel : s'il n'est pas installé, il est téléchargé automatiquement.

Installation

pip install -r requirements.txt

Ou via pip (rend la commande mcp2term disponible) :

pip install .

Configuration

Copier et éditer le fichier .env :

cp .env.example .env

Variables disponibles :

* Sans token ni auth, le tunnel ngrok ne s'ouvre pas ; le serveur reste accessible en local uniquement.
Obtenir un token : https://dashboard.ngrok.com/authentication

Utilisation

# Démarrage normal (ngrok en arrière-plan)
python mcp2term.py

# Mode local uniquement (pas de tunnel ngrok)
python mcp2term.py --local-only

# Options personnalisées
python mcp2term.py --port 9000 --host 0.0.0.0 --log-level DEBUG

# Réutiliser une config ngrok déjà en place (domaine réservé, région...)
python mcp2term.py --ngrok-config ~/.config/ngrok/ngrok.yml
python mcp2term.py --ngrok-config ~/.config/ngrok/ngrok.yml --ngrok-tunnel-name mon-tunnel

La version du schéma (tunnels: v2 ou endpoints: v3) est détectée automatiquement à partir du champ version: du fichier de config.

Limitation avec --ngrok-tunnel-name sur une config v3 : NGROK_BASIC_AUTH est ignoré (l'API v3 rejette ce champ pour un endpoint nommé). Pour protéger un tunnel nommé v3, configurer l'authentification directement sur l'endpoint dans le fichier ngrok.yml (traffic_policy), ou ne pas utiliser --ngrok-tunnel-name.

Options CLI

Ce qui se passe au lancement

1. Démarre un shell interactif (cmd.exe sur Windows, bash sur Unix)

2. Lance le serveur MCP en local (immédiatement, sans attendre ngrok)

3. En arrière-plan : télécharge ngrok si nécessaire, configure le token, tente d'ouvrir un tunnel (2 tentatives avec retry)

4. Si le tunnel est établi : affiche l'URL publique

5. Si le tunnel échoue : le serveur reste accessible en local

6. Surveillance : un thread vérifie l'état du tunnel toutes les 30s (backoff x2 en cas d'erreur) et le reconnecte automatiquement si perdu

Outils MCP

Détail des outils

execute_command(command, timeout=15)

Le shell conserve l'état (répertoire courant, variables d'environnement) entre les commandes.

• timeout : temps max d'attente de la sortie (défaut: 15s). Passer à 60s+ pour les commandes longues.

• Le shell est automatiquement réinitialisé après 10 minutes d'inactivité.

read_file(path) et write_file(path, content)

Les chemins sont résolus relativement au répertoire courant du shell.
Les traversées de répertoire (../) sont bloquées.
Taille max : 10 MB.

Mode interactif (PTY)

execute_command utilise de simples pipes : les programmes plein écran/curses (nano, vim, top, htop) ne peuvent pas s'y afficher correctement. Le mode interactif alloue un vrai PTY à un processus séparé et restitue l'écran rendu en texte (via pyte, un émulateur de terminal VT100 pur Python) au lieu des séquences ANSI brutes.

Exemple : start_interactive("nano fichier.txt") → send_keys("hello") → send_keys("<CTRL-X>") → send_keys("y<ENTER>") → stop_interactive().

Syntaxe des touches (send_keys) : le texte littéral est envoyé tel quel ; les touches spéciales s'écrivent entre chevrons : <ENTER> <ESC> <TAB> <BACKSPACE> <UP> <DOWN> <LEFT> <RIGHT> <HOME> <END> <PGUP> <PGDN> et <CTRL-X> (n'importe quelle lettre).

Limitations :

• Une seule session interactive à la fois — stop_interactive avant d'en démarrer une autre encore en cours.

• Modèle "instantané" : read_screen retourne l'état actuel de l'écran, pas un flux vidéo continu. Pour un programme qui se rafraîchit tout seul (top, htop), il faut interroger read_screen à nouveau pour voir l'évolution.

• Linux/macOS uniquement (POSIX) — retourne une erreur explicite sur Windows.

Configuration client (ChatGPT / Claude Desktop)

Ajouter un serveur MCP distant :

• URL : https://votre-sous-domaine.ngrok.io/mcp

• Type : Streamable HTTP

• Authentification : Basic Auth (utilisateur/mot de passe du .env)

Sécurité

Rate Limiting

Le serveur limite chaque session à 30 appels d'outils par minute. Au-delà, une erreur est retournée.

Protection anti-traversal

read_file et write_file vérifient que le chemin résolu reste dans le répertoire de base du shell. Les tentatives de ../ sont bloquées.

Masquage des credentials

Les tokens et mots de passe sont systématiquement masqués dans les logs (****).

Journalisation des sessions

Chaque appel d'outil est horodaté avec un identifiant de session, permettant le traçage des actions.

Docker

docker build -t mcp2term .
docker run -it --rm -p 8765:8765 -v ./.env:/app/.env mcp2term --local-only

Le shell s'exécute dans le conteneur : bash, curl, git et nano sont préinstallés.
Les fichiers créés par les commandes sont perdus à l'arrêt du conteneur sauf si tu montes un volume :

docker run -it --rm -p 8765:8765 -v "$PWD/data:/workspace" -w /workspace mcp2term

Ajouter des outils au conteneur

Édite le Dockerfile et ajoute la ligne dans la section dédiée :

RUN apt-get install -y --no-install-recommends nodejs
# ou via pip
RUN pip install --no-cache-dir poetry

Reconstruis l'image : docker build -t mcp2term .

Tests

pip install pytest httpx
python -m pytest tests/ -v

Tests d'intégration : initialisation, liste des outils, exécution de commande, health check, mode interactif (démarrage/envoi de touches/redimensionnement/ arrêt, refus d'une seconde session concurrente).
Le serveur est automatiquement démarré/arrêté par les fixtures pytest.

La fidélité de rendu de programmes complets comme nano/vim/htop (dépendante de TERM/terminfo) n'est pas testée en CI — à vérifier manuellement avec un client réel après toute modification du mode interactif.

Dépendances

• mcp — SDK MCP officiel (Anthropic)

• pyngrok — Client Python pour ngrok (auto-installation du binaire)

• python-dotenv — Chargement du .env

• pyte — Émulateur de terminal VT100 pur Python, utilisé pour restituer un écran texte lisible en mode interactif

Logs

Activer avec LOG_LEVEL=DEBUG dans .env ou --log-level DEBUG.