Terminal Controller for MCP

MCP用端末コントローラ

標準化されたインターフェースを通じて、安全な端末コマンド実行、ディレクトリナビゲーション、およびファイルシステム操作を可能にするモデルコンテキストプロトコル (MCP) サーバー。

特徴

• コマンド実行: タイムアウト制御と包括的な出力キャプチャを備えたターミナルコマンドを実行します。
• ディレクトリ管理: 直感的なフォーマットでディレクトリの内容をナビゲートして一覧表示します
• セキュリティ対策: 危険なコマンドや操作に対する安全策を内蔵
• コマンド履歴: 最近実行したコマンドを追跡して表示します
• クロスプラットフォームサポート: WindowsとUNIXベースのシステムの両方で動作します
• ファイル操作: 行レベルの精度でファイルの内容の読み取り、書き込み、更新、挿入、削除を実行します。

インストール

Smithery経由でインストール

Smithery経由で Claude Desktop のターミナル コントローラーを自動的にインストールするには:

前提条件

• Python 3.11以上
• MCP 互換クライアント (Claude Desktop など)
• UV/UVX搭載（オプション、UVX方式用）

方法1: PyPIのインストール（推奨）

PyPI から直接パッケージをインストールします。

または、UV を使用する場合:

方法2: ソースから

ソースからインストールしたい場合:

1. このリポジトリをクローンします:
   git clone https://github.com/GongRzhe/terminal-controller-mcp.git cd terminal-controller-mcp
2. セットアップ スクリプトを実行します。
   python setup_mcp.py

クライアント構成

クロードデスクトップ

Claude Desktop をターミナル コントローラーを使用するように構成するには、次の 2 つの方法があります。

オプション1: UVXの使用（推奨）

Claude Desktop 構成ファイルに以下を追加します。

オプション2: Pythonを直接使用する

構成パスはオペレーティング システムによって異なります。

• macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows : %APPDATA%\Claude\claude_desktop_config.json

カーソル

カーソルについては、Claude Desktop と同様の構成設定を使用します。

その他のMCPクライアント

その他のクライアントについては、外部 MCP サーバーを構成する方法については、そのクライアントのドキュメントを参照してください。

使用法

設定が完了すると、MCP クライアントを介して自然言語を使用して端末と対話できるようになります。

• 「現在のディレクトリでコマンドls -laを実行します」
• 「マイドキュメントフォルダへ移動」
• 「ダウンロードディレクトリの内容を表示」
• 「最近のコマンド履歴を表示」
• 「config.jsonの内容を読み取る」
• 「script.py ファイルの 5 行目を 'print("Hello World")' で更新します」
• 「ログファイルから10行目から15行目を削除します」
• 「テキストファイルの先頭に新しい行を挿入する」

APIリファレンス

ターミナル コントローラは次の MCP ツールを公開します。

execute_command

ターミナルコマンドを実行し、その結果を返します。

パラメータ:

• command : 実行するコマンドラインコマンド
• timeout : コマンドのタイムアウト（秒）（デフォルト: 30）

戻り値:

• stdout、stderr、実行ステータスを含むコマンド実行の出力

get_command_history

最近のコマンド実行履歴を取得します。

パラメータ:

• count : 返される最近のコマンドの数（デフォルト: 10）

戻り値:

• フォーマットされたコマンド履歴レコード

get_current_directory

現在の作業ディレクトリを取得します。

戻り値:

• 現在の作業ディレクトリのパス

change_directory

現在の作業ディレクトリを変更します。

パラメータ:

• path : 切り替え先のディレクトリパス

戻り値:

• 操作結果情報

list_directory

指定されたディレクトリ内のファイルとサブディレクトリを一覧表示します。

パラメータ:

• path : リストの内容へのディレクトリパス（デフォルト: 現在のディレクトリ）

戻り値:

• ディレクトリとファイルのアイコンでフォーマットされたディレクトリの内容のリスト

write_file

上書きまたは追加のオプションを使用して、ファイルにコンテンツを書き込みます。

パラメータ:

• path : ファイルへのパス
• content : 書き込む内容
• mode : 書き込みモード（'overwrite' または 'append'、デフォルト: 'overwrite'）

戻り値:

• 書き込み成功の検証を含む操作結果情報

read_file

オプションの行選択を使用してファイルからコンテンツを読み取ります。

パラメータ:

• path : ファイルへのパス
• start_row : 読み取り開始行（0から始まる、オプション）
• end_row : 読み取り終了行（0 ベース、含む、オプション）

戻り値:

• ファイルの内容または選択した行

insert_file_content

ファイル内の特定の行にコンテンツを挿入します。

パラメータ:

• path : ファイルへのパス
• content : 挿入するコンテンツ
• row : 挿入する行番号（0から始まる、オプション）
• rows : 挿入する行番号のリスト（0から始まる、オプション）

戻り値:

• 操作結果情報

delete_file_content

ファイルから特定の行のコンテンツを削除します。

パラメータ:

• path : ファイルへのパス
• row : 削除する行番号（0から始まる、オプション）
• rows : 削除する行番号のリスト（0から始まる、オプション）

戻り値:

• 操作結果情報

update_file_content

ファイル内の特定の行のコンテンツを更新します。

パラメータ:

• path : ファイルへのパス
• content : 指定された行に配置する新しいコンテンツ
• row : 更新する行番号（0から始まる、オプション）
• rows : 更新する行番号のリスト（0から始まる、オプション）

戻り値:

• 操作結果情報

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

ターミナル コントローラは、いくつかのセキュリティ対策を実装しています。

• 長時間実行されるコマンドを防ぐためのタイムアウト制御
• 危険なコマンドのブラックリスト化 (rm -rf /、format、mkfs)
• 適切なエラー処理とコマンド実行の分離
• 明示的に許可されたコマンドとディレクトリのみへのアクセス

制限事項

• タイムアウト期間内に完了したコマンドのみが結果を返します
• デフォルトでは、サーバーはそれを実行しているユーザーと同じファイルシステム権限にアクセスできます。
• 端末インターフェースの非対話型の性質により、一部の対話型コマンドが期待どおりに動作しない場合があります。

トラブルシューティング

問題が発生した場合:

1. Pythonのバージョンが3.11以上であることを確認してください
2. Claude Desktop の設定が正しいことを確認してください
3. エラーを確認するには、ターミナル コントローラーを直接実行してみてください。
   python -m terminal_controller
4. UVX 関連の問題については、以下を試してください。
   uvx terminal_controller
5. MCPクライアントのログで接続エラーを確認します

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。

ライセンス

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