MCP ターミナルサーバー

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

特徴

Windowsサービスとして実行するかデバッグモードで実行する
シェルコマンドを実行し、その出力をリアルタイムでストリーミングする
APIキー認証
レート制限
環境変数または設定ファイルで設定可能
堅牢なエラー処理とログ記録
障害時の自動プロセス再起動

インストール

前提条件

Windows オペレーティングシステム
Python 3.7以上
管理者権限（サービスのインストール用）

インストール手順

このリポジトリをクローンするか、ソースコードをダウンロードしてください
PowerShellを管理者として開く
プロジェクトディレクトリに移動する
インストールスクリプトを実行します。

.\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 : カスタム構成ファイルへのパス

構成

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

環境変数
設定ファイル (config.json)
インストール時のコマンドライン引数

設定ファイル

サンプル設定ファイル（ 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イベントビューアでサービス関連のエラーを確認する

ライセンス

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

MCP Terminal Server

Integrations