desktop-commander-overview

Desktop Commander MCP

Desktop Commander を使うと、エージェントはユーザーの実際のコンピューター上にあるファイル、フォルダー、ターミナル、プロセス、構造化ドキュメント、SSH 経由で接続可能なリモートマシンを操作できます。ツールの詳細なスキーマ（パラメーター、戻り値の形式、形式固有の動作）は MCP 自体に記載されています。このスキルでは、ツールでできることと、一般的なワークフローでの組み合わせ方を説明します。

この MCP でエージェントにできること

永続的なシェルセッション。 Desktop Commander は、起動したプロセスやセッションを複数のツール呼び出しにわたって維持します。単一の長時間実行シェル、REPL、SSH セッションでは状態が引き継がれるため、環境変数、作業ディレクトリ、有効化した仮想環境、開いた接続、REPL の変数などが保持されます。そのため、エージェントは cd で移動し、仮想環境を有効化してから、同じセッションに対して何ターンも後にコマンドやコードを送信でき、再設定は不要です。（注：別々の start_process 呼び出しでは別々のセッションが開かれ、シェルの状態は共有されません。状態が維持されるのは各セッション内であり、セッション間ではありません。）

長時間実行プロセス。 開発サーバー、ウォッチャー、ビルド、トレーニング、テストスイートをバックグラウンドで起動し、そのまま作業を続けられます。MCP はプロセスハンドルを返すため、エージェントは何ターンにもわたって出力を追跡したり、操作したり、終了したりできます。長時間実行コマンドの終了を待つために、フォアグラウンドコマンドでワークフローを止める必要はありません。

IDE ワークスペースを超えたファイルシステムへのアクセス。 ユーザーがアクセスを許可した範囲であれば、ダウンロード、書類、IDE 外のプロジェクトフォルダー、その他の許可されたフォルダーなど、どこにあるファイルでも読み取り、書き込み、移動、一覧表示、確認ができます。整理やクリーンアップの作業、ドキュメントの一括処理、IDE のサンドボックス内では対応できない「同僚からたった今送られてきたファイルを見て」という依頼に便利です。

既存ファイルへのピンポイントな編集。 edit_block ツールは、組み込みの安全機能を備えた完全一致の検索・置換を行います。一致箇所が曖昧な場合は、誤った箇所を黙って上書きせず、明確にエラーになります。また、expected_replacements の数を指定することで、一部だけが一致して事故につながるのを防げます。読み取った範囲をもとにファイル全体を書き換える方法よりも、データ損失のリスクは低くなります。ただし、誤った old_string や expected_replacements を指定すると内容が破損する可能性はあるため、編集が完了したと判断する前に変更後の内容を確認してください。

バイナリファイルと構造化ファイルを MCP で直接処理。 Excel、DOCX、PDF はファーストクラスでサポートされており、テキストだけを使った近似処理ではなく、形式固有の方法で読み取り、変更できます。Excel はセル範囲の JSON、DOCX は生の XML 編集、PDF は新しい出力ファイルへのページ単位の操作で処理します。生成されるのは元の形式の実ファイルであり、再生成された近似版ではありません。画像と PDF は、エージェントが表示できるコンテンツとして返されます。

大規模な検索。 ストリーミングと ripgrep を利用し、プロジェクト全体やフォルダーツリーを検索できます。エージェントはファイル名検索とファイル内コンテンツ検索を選択し、結果を一度に大量に表示することなく段階的にページ送りできます。また、検索語句が曖昧な場合は、複数の検索を同時に実行します。

SSH 経由でリモートマシンに接続。 永続シェル内で長時間実行される SSH セッションを使うと、エージェントを実用的な運用ツールとして利用できます。一度接続すれば、各手順で再接続することなく、何ターンにもわたってログの追跡、診断の実行、デプロイ、デバッグを行えます。

プロセス管理。 OS の権限に応じて、アクセス可能なプロセスの一覧表示、確認、出力の追跡、終了ができます。以前のセッションで残った開発サーバーのクリーンアップや、CPU／メモリの問題の診断に便利です。

ワークフローの例

各例では、実際に使用するツールの呼び出し順を示します。以下の呼び出しは疑似コードの省略表記（tool_name("arg", flag=value)）で記載しています。実際のツールはオブジェクト形式の引数を受け取ります。ツールの説明と完全なパラメーター一覧は MCP 自体に記載されています。

「本番環境の問題をデバッグする」

本番環境に影響する SSH コマンドを実行する前に、実行する操作を説明し、リスクが無視できない場合はユーザーの確認を得てください。

start_process("ssh [email protected]", timeout_ms=...) を実行すると、長時間稼働する SSH セッションが開き、PID が返されます。interact_with_process(pid, "tail -f /var/log/app.log\n") でログのストリーミングを開始します。以降のターンでは、ログが届くたびに末尾の 50 行を確認するには read_process_output(pid, offset=-50) を、同じセッションで診断コマンドを実行するには interact_with_process(pid, "...") を使用します。作業が終わったら force_terminate(pid) でセッションを閉じます。start_process で開いたセッションの終了には force_terminate が適切なクリーンアップツールです。kill_process は list_processes で見つけた任意の OS PID に使用します。

「これをステージング環境にデプロイする」

デプロイ、再起動、マイグレーション、または環境を変更するその他のコマンドを実行する前に、ユーザーがその操作を明示的に依頼済みでない限り、操作の概要を説明し、確認を得てください。

デプロイコマンドには start_process を使用します（スクリプト、SSH 経由のコマンド、kubectl／gh などを使用できます）。出力を追跡し、エラーを確認するには read_process_output を使用します。デプロイ時に対話形式の確認が必要な場合は、interact_with_process(pid, "yes\n") を使用します。エージェントが完了またはロールバックを確認している間、セッションは稼働し続けます。

「開発サーバーを実行して、API を反復的に改善する」

start_process("npm run dev", timeout_ms=...) でサーバーを稼働させ続けます。その後、エージェントは次のループを繰り返します。ルートファイルに対して edit_block を実行し、サーバーの再読み込みを確認するために read_process_output(pid, offset=-30) を実行し、1 回限りのテストには start_process("curl -s http://localhost:3000/api/...") を実行します。コードを変更しても、開発サーバーを再起動する必要はありません。

「このモノレポ全体をリファクタリングする」

start_search(pattern="oldFunctionName", path=repo_root, searchType="content") で、すべての呼び出し箇所を検索対象にします。get_more_search_results(sessionId) で結果をページ単位で取得します。文脈を確認して曖昧なヒットを特定するには、read_multiple_files(paths=[...]) を使用します。各箇所で edit_block(file_path, old_string, new_string) を実行します。同じ部分文字列が 1 つのファイル内に正当に複数回出現する場合は、expected_replacements を設定します。古い名前で start_search を再実行し、検索が完了するまで get_more_search_results(sessionId) で結果を取得して検証してください。残りのヒットがゼロだと確認できるのは、その後です。

「このスプレッドシートの第 3 四半期の数値を更新して、レポートの概要を調整する」

read_file(path="/.../q3.xlsx", sheet="Revenue", range="A1:F50") は、既存の数値を JSON の 2 次元配列として返します。edit_block(file_path="/.../q3.xlsx", range="Revenue!C12:C24", content=[[12345], ...]) でセルを直接更新します。レポートの DOCX 編集は 2 回読み込む手順です。まず read_file(path="/.../report.docx")（offset 0）を実行すると、文書のアウトライン（見出しと段落テキスト）が返され、概要セクションの場所を特定できます。次に read_file(path="/.../report.docx", offset=N, length=...) を N > 0 の条件で実行すると、そのセクション周辺の基になる XML が返されます。オフセットにゼロ以外の値を指定することで、読み込みが XML モードに切り替わります。その出力から XML 断片をコピーして old_string として使い、書き換えた XML を指定して edit_block(file_path, old_string, new_string) を呼び出します。ユーザーが受け取るのは、再生成された近似ファイルではなく、実際の .xlsx ファイルと .docx ファイルです。

「第 3 四半期のレポートを PDF として生成する」

Markdown コンテンツ（ヘッダー、テーブル、埋め込み HTML によるチャート）を作成し、write_pdf を呼び出して新しい PDF ファイルにレンダリングします。MCP の write_pdf ツールの説明に、正確なパラメーターとファイル名の規則が記載されています。それに従ってください。

「この PDF に表紙を挿入する」

write_pdf は、操作の配列（ページの挿入／削除）を指定して既存の PDF を変更することにも対応しています。表紙の追加、セクションの削除、別のファイルのコンテンツの結合など、新しい PDF を生成する既存 PDF の編集に使用してください。操作の形式とパラメーターの規則については、write_pdf ツールの説明を参照してください。

「この 200MB の CSV を分析する」

start_process("python3 -i", timeout_ms=...) を実行すると Python REPL が開き、PID が返されます。interact_with_process(pid, "import pandas as pd; df = pd.read_csv('/abs/path.csv')") で一度だけ読み込みます。その後の質問はすべて、df.describe()、df.groupby('col').size()、グラフの作成など、すでに読み込み済みの同じ REPL で実行されます。ライブラリを再インポートする必要はなく、データフレームも再読み込みされません。MCP 自体も、ローカルのデータファイルを分析する際はこのワークフローを推奨しています。

「簡単な Node スクリプトを実行する」

start_process("node:local", timeout_ms=...) を実行すると、MCP サーバー自体でステートレスな Node 実行モードが開きます。ES のインポートに対応しています。start_process でランナーを開き、各 JavaScript コードを interact_with_process(pid, "<your JS here>") で送信すると、個別に実行されます（呼び出し間で状態は共有されません）。長時間稼働する REPL を維持するほどではない、一度限りの変換に適しています。start_process のコマンド引数にコードを入れないでください。ここに指定するのはランナーの種類（node:local）だけです。

「このコードベースを説明する」

まず list_directory(path=repo_root, depth=3) で構成を確認します。次に start_search(pattern="export ", path=repo_root, searchType="content") で公開インターフェースを探します。read_multiple_files(paths=[entrypoints]) で実際のコードを確認します。エージェントは、ユーザーに探す場所を尋ね直すことなく、対象を絞り込んでいけます。

「Downloads フォルダーを整理する」

まずパスを絶対パスに解決します（例：~/Downloads ではなく /Users/<user>/Downloads）。次に list_directory(path="/Users/<user>/Downloads", depth=1) で内容を確認します。start_search(pattern="*.pdf", path="/Users/<user>/Downloads", searchType="files") などを使い、ほかのファイル形式も検索します。新しいフォルダーには create_directory を使います。各項目を move_file で移動します。破壊的な操作を実行する前に、移動計画をプレビューしてください。

「オンボーディングして — 前回のセッションでは何をしていた？」

get_recent_tool_calls(maxResults=200) で、引数と出力を含む最近のアクティビティを取得できます。list_sessions で、まだ実行中のターミナルセッションを確認できます。list_searches で、進行中の検索を確認できます。list_processes で、まだ実行中のプロセスを確認できます。これらを組み合わせると、ユーザーに作業内容を説明し直してもらわずに状況を再構成できます。

「REPL が応答しないのはなぜ？」

list_sessions を確認します。Blocked: true の場合、REPL はハングしているのではなく、入力待ちです。read_process_output(pid, offset=-100) で最後の出力を確認します（多くの場合、プロンプトが表示されています）。interact_with_process(pid, "<the input it's waiting for>\n") で入力を渡すと、ブロックが解除されます。

コアツール一覧

エージェントが最もよく使うツールをまとめた一覧です。すべてを網羅しているわけではありません。この一覧にない設定、診断、フィードバック用ツールも MCP から利用できます。すべてのツールの詳細なパラメーターと戻り値の形式は、MCP 独自のツール説明に記載されています。

• プロセス／シェル： start_process、interact_with_process、read_process_output、list_processes、list_sessions、kill_process、force_terminate
• ファイル（読み書き）： read_file、read_multiple_files、write_file、edit_block、write_pdf
• ファイルシステム： list_directory、get_file_info、move_file、create_directory
• 検索： start_search、get_more_search_results、list_searches、stop_search
• 診断／設定： get_recent_tool_calls、get_config

規約

絶対パスを優先してください。 相対パスは作業ディレクトリによって失敗する場合があり、チルダを使ったパス（~/...）もすべてのコンテキストで展開されるとは限りません。絶対パスが最も確実なので、可能な限り絶対パスを渡してください。

許可されたディレクトリの範囲。 ファイル操作は、ユーザーが設定した allowedDirectories 内でのみ機能します。list_directory の出力に [DENIED] マーカーが表示されたり、パスが範囲外の場合に read_file ／ write_file が拒否されたりすることがあります。拒否されたパスをユーザーに伝えてください。再試行はしないでください。

macOS で実行する場合： デフォルトのシェルは zsh です。python ではなく python3 を使用してください。一部の GNU ツールには、GNU sed の gsed のように接頭辞が付いた名前が使われます。一般的なパッケージマネージャーは brew です。open はターミナルからファイルやアプリを開き、mdfind は Spotlight を使ったファイル名の完全一致検索を最速で実行します。上記を前提とする前に、get_config（またはシェルから process.platform ／ uname を調べる方法）でホストのプラットフォームを検出してください。Windows と Linux のホストでは動作が異なります。

ページネーション。 ファイルの読み取り、プロセスの出力、検索結果など、長い出力はすべて offset と length に対応しています。負のオフセットを指定すると末尾から読み取ります（テールモード）。大量の結果をコンテキストに出力するのではなく、これらを使用してください。