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

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.

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

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

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