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

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 :

Variable	Obligatoire	Description
NGROK_AUTH_TOKEN	Non*	Token d'authentification ngrok
NGROK_BASIC_AUTH	Non*	Identifiants au format user:password
HOST	Non	Adresse d'écoute locale (défaut: 127.0.0.1)
PORT	Non	Port local (défaut: 8765)
LOG_LEVEL	Non	DEBUG, INFO (défaut), WARNING, ERROR
LOG_FILE	Non	1 pour écrire aussi dans mcp2term.log

* 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

Options CLI

Option	Description
--host HOST	Adresse d'écoute (défaut: 127.0.0.1)
--port PORT	Port d'écoute (défaut: 8765)
--log-level LEVEL	DEBUG, INFO, WARNING, ERROR
--local-only	Désactive le tunnel ngrok
--help	Affiche l'aide

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

Outil	Paramètres	Description
execute_command	command, timeout=15	Exécute une commande shell (état persistant)
change_directory	path	Change le répertoire courant
get_shell_state	—	Retourne le dossier courant, le type de shell et le PID
reset_shell	—	Tue et relance le shell
interrupt_command	—	Envoie Ctrl+C à la commande en cours
send_stdin	data	Envoie du texte à l'entrée standard (commandes interactives)
read_file	path	Lit un fichier (protection anti-traversal, max 10 MB)
write_file	path, content	Écrit un fichier (création des dossiers parents si nécessaire, max 10 MB)
health_check	—	Statut : uptime, URL ngrok, nombre de commandes, état du shell

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.

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

4 tests d'intégration : initialisation, liste des outils, exécution de commande, health check.
Le serveur est automatiquement démarré/arrêté par les fixtures pytest.

Dépendances

• mcp — SDK MCP officiel (Anthropic)
• pyngrok — Client Python pour ngrok (auto-installation du binaire)
• python-dotenv — Chargement du .env

Logs

Niveau	Usage
INFO	Démarrage, arrêt, URL ngrok, commandes exécutées, fichiers écrits
WARNING	Timeouts, rate limit, erreurs tunnel, traversées de répertoire
DEBUG	Appels d'outils, stdin/stdout brut, état du tunnel, reconnexion, send_stdin

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