MCP ターミナルサーバー

Windows サービスとして実行でき、シェル コマンドを実行してその出力をストリーミングするためのエンドポイントを公開する軽量の FastAPI サーバーです。

特徴

• Windowsサービスとして実行するかデバッグモードで実行する

• シェルコマンドを実行し、その出力をリアルタイムでストリーミングする

• APIキー認証

• レート制限

• 環境変数または設定ファイルで設定可能

• 堅牢なエラー処理とログ記録

• 障害時の自動プロセス再起動

Related MCP server: Shell MCP Server

インストール

前提条件

• Windows オペレーティング システム

• Python 3.7以上

• 管理者権限（サービスのインストール用）

インストール手順

1. このリポジトリをクローンするか、ソースコードをダウンロードしてください

2. PowerShellを管理者として開く

3. プロジェクトディレクトリに移動する

4. インストール スクリプトを実行します。

.\install_service.ps1

これにより、次のようになります。

• 必要なPython依存関係をインストールする

• ランダムな API キーを生成する（または提供したキーを使用する）

• 設定ファイルを作成する

• Windowsサービスをインストールして開始する

インストールオプション

次のパラメータを使用してインストールをカスタマイズできます。

.\install_service.ps1 -ApiKey "your-api-key" -Port 8080 -Host "127.0.0.1" -LogLevel "debug"

利用可能なパラメータ:

• -ApiKey : 認証用のカスタムAPIキー

• -Port : サーバーのポート番号（デフォルト: 8000）

• -Host : バインドするホストアドレス（デフォルト: 0.0.0.0）

• -LogLevel : ログレベル (デバッグ、情報、警告、エラー、クリティカル)

• -ConfigFile : カスタム構成ファイルへのパス

構成

サーバーは以下を通じて構成できます。

1. 環境変数

2. 設定ファイル (config.json)

3. インストール時のコマンドライン引数

設定ファイル

サンプル設定ファイル（ config.json.sample ）が提供されています。これをconfig.jsonにコピーして変更することができます。

{
    "host": "0.0.0.0",
    "port": 8000,
    "log_level": "info",
    "log_file": "mcp_terminal_server.log",
    "max_log_size_mb": 10,
    "log_backup_count": 5,
    "restart_on_failure": true,
    "max_restart_attempts": 5,
    "restart_delay_seconds": 10,
    "shutdown_timeout_seconds": 30,
    "working_directory": null
}

環境変数

環境変数を使用してサーバーを構成することもできます。

• MCP_TERMINAL_API_KEY : 認証用のAPIキー

• MCP_HOST : バインドするホストアドレス

• MCP_PORT : サーバーのポート番号

• MCP_LOG_LEVEL : ログレベル

• MCP_LOG_FILE : ログファイルへのパス

• MCP_MAX_LOG_SIZE_MB : ログファイルの最大サイズ（MB）

• MCP_LOG_BACKUP_COUNT : 保存するログバックアップファイルの数

• MCP_RESTART_ON_FAILURE : 障害時にサーバーを再起動するかどうか

• MCP_MAX_RESTART_ATTEMPTS : 再起動の最大試行回数

• MCP_RESTART_DELAY_SECONDS : 再起動の試行間の遅延

• MCP_SHUTDOWN_TIMEOUT_SECONDS : 正常なシャットダウンのタイムアウト

• MCP_WORKING_DIRECTORY : サーバーの作業ディレクトリ

サービス管理

サービスコマンド

次のコマンドを使用してサービスを管理できます。

# Install the service
python service.py install

# Start the service
python service.py start

# Stop the service
python service.py stop

# Restart the service
python service.py restart

# Remove the service
python service.py remove

# Update the service configuration
python service.py update

# Run in debug mode (not as a service)
python service.py debug

ログ

ログは設定されたログファイル（デフォルト： mcp_terminal_server.log ）に保存されます。ログには以下が含まれます。

• サービスの開始/停止イベント

• コマンド実行

• エラーと警告

• 健康診断結果

APIの使用

テストクライアント

次の機能を使用してサーバーと対話するための堅牢なテスト クライアントが提供されます。

• 使いやすさを向上させるコマンドライン引数

• APIキー認証のサポート

• 読みやすさを向上させるカラー出力

• 出力をファイルに保存するサポート

• 堅牢なエラー処理とログ記録

• コマンド履歴付きの対話型モード

• サーバーヘルスチェック機能

基本的な使い方

# Run a command
python test_client.py -c "dir" -k "your-api-key"

# Check server health
python test_client.py --health

# Interactive mode
python test_client.py -k "your-api-key"

# Save output to a file
python test_client.py -c "systeminfo" --save-output output.txt

# Specify server URL
python test_client.py -s "http://example.com:8000" -c "dir"

# Enable verbose output
python test_client.py -v -c "dir"

# Show version
python test_client.py --version

設定ファイル

テストクライアントはJSON設定ファイルを使用して設定できます。提供されているサンプルに基づいてclient_config.jsonファイルを作成してください。

{
    "server_url": "http://localhost:8000",
    "api_key": "your-api-key-here",
    "timeout": 60,
    "verbose": false
}

次に、次のように使用します。

python test_client.py --config client_config.json

環境変数

テスト クライアントは、環境変数による構成もサポートしています。

• MCP_TERMINAL_API_KEY : 認証用のAPIキー

• MCP_TERMINAL_SERVER_URL : サーバーURL

APIエンドポイント

• POST /run : コマンドを実行する

  • X-API-Keyヘッダーに API キーが必要です

  • リクエスト本文: {"command": "your command"}

  • コマンド出力を含むストリーミング応答を返します

• GET /health : サーバーの健全性をチェックする

  • {"status": "healthy", "active_sessions": 0}を返します

セキュリティに関する考慮事項

• 本番環境では常にデフォルトのAPIキーを変更する

• サーバーにローカルからのみアクセスできるようにする場合は、ホストを127.0.0.1に制限します。

• 本番環境ではHTTPSの使用を検討する

• サーバーは潜在的に危険なコマンドをブロックしますが、追加のセキュリティ対策が必要になる場合があります。

トラブルシューティング

• ログファイルでエラーを確認してください

• コンソール出力を確認するには、デバッグモードで実行します: python service.py debug

• サービスが実行されていることを確認します: Get-Service -Name "MCP_Terminal_Server"

• Windowsイベントビューアでサービス関連のエラーを確認する

ライセンス

マサチューセッツ工科大学