MCP ターミナルサーバー

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

特徴

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

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

• APIキー認証

• レート制限

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

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

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

Related MCP server: Shell MCP Server

インストール

前提条件

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

• Python 3.7以上

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

インストール手順

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

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

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

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

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

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

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

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

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

インストールオプション

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

利用可能なパラメータ:

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

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

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

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

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

構成

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

1. 環境変数

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

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

設定ファイル

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

環境変数

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

• 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 : サーバーの作業ディレクトリ

サービス管理

サービスコマンド

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

ログ

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

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

• コマンド実行

• エラーと警告

• 健康診断結果

APIの使用

テストクライアント

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

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

• APIキー認証のサポート

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

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

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

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

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

基本的な使い方

設定ファイル

テストクライアントはJSON設定ファイルを使用して設定できます。提供されているサンプルに基づいて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イベントビューアでサービス関連のエラーを確認する

ライセンス

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