remote-pc-mcp

remote-pc-mcp

シェル、ファイルシステム、バックグラウンドプロセス、システム統計、スクリーンショット、UI 操作、ファイル転送など、あらゆる PC の機能をストリーミング可能な HTTP 経由で あらゆる MCP クライアント（Claude Desktop、Claude Code、Cursor、Cline、Continue、Windsurf、カスタムエージェントなど、Model Context Protocol に対応するもの）に公開します。

リモート操作したい任意のマシンに配置できます。ホームサーバー、デスクトップ PC、ビルド／CI マシン、メディアサーバー、ワークステーション、Raspberry Pi などが対象です。別のマシンから、お好みの AI エージェントを使ってコマンドを実行したり、ファイルを管理したり、バックグラウンドジョブを起動・監視したり、スクリーンショットを撮影したり、デスクトップ UI を操作したりできます。

通信には mcp SDK のストリーミング可能な HTTP（stateless_http=True）を使用するため、サーバーを再起動しても、すでに接続しているクライアントには影響しません。各リクエストは自己完結しており、古くなるインメモリーセッションはありません。

⚠️ shell_exec は、サーバーを起動したユーザーとしてホスト上で任意のコマンドを実行します。 ベアラートークンは root 相当の認証情報です。サーバーを公開する前に、セキュリティを確認してください。

ツール

ツール	説明
shell_exec	任意のシェルコマンドを実行します。stdout、stderr、終了コードを返します
read_file	ファイルをテキストまたは base64 で読み取ります（バイナリーの場合はフォールバック）
write_file	テキストまたはバイナリーコンテンツをファイルに書き込みます
list_directory	ファイルとディレクトリを一覧表示します。再帰表示も可能です
system_info	OS、CPU、RAM、GPU の統計情報を取得します（NVIDIA GPU は nvidia-smi 経由。GPU のないホストでは利用できません）
start_process	長時間実行するコマンドをバックグラウンドで起動し、PID を返します
get_process_output	PID を指定してバックグラウンドプロセスの stdout／stderr をポーリングし、終了後は終了コードも取得します
kill_process	PID を指定してプロセスを終了します
download_file	URL からこのマシンに直接ファイルをダウンロードします
take_screenshot	すべてのモニターを含むデスクトップ全体を、ビジョンモデル向けのサイズで画像としてキャプチャします（画面座標）
click	スクリーンショット上の (x, y) をクリックします。左／右／中央ボタン、シングルクリックまたはマルチクリックに対応します
move_mouse	スクリーンショット上の (x, y) にカーソルを移動します。アニメーション移動も可能です
type_text	フォーカス中のウィンドウに文字列を入力します
press_key	単一キーまたはホットキーの組み合わせを押します（例：enter、f11、ctrl+c、win+d）
scroll	マウスホイールを上下にスクロールします。特定の位置でのスクロールも可能です

要件

• Python 3.10+
• Windows 10/11、または systemd を備えた Linux（自動起動用）

インストール

操作したいマシンで実行します。

git clone https://github.com/raghibrm/remote-pc-mcp
cd remote-pc-mcp
cp .env.example .env

.env に強力なトークンを設定します。

REMOTE_PC_MCP_TOKEN=your-long-random-token-here

トークンを生成するには、次を実行します。

# Windows
python -c "import secrets; print(secrets.token_hex(32))"

# Linux / macOS
openssl rand -hex 32

その後、インストーラーを実行します。

# Windows
install.bat

# Linux
chmod +x install.sh
./install.sh

これだけです。コマンドは 1 つです。インストーラーは次の処理を行います。

• Python の依存関係をインストールします
• ログインのたびにサーバーが非表示で起動するよう登録します（Windows ではスタートアップフォルダーのショートカット、Linux では systemd のユーザーユニット）
• サーバーをただちに起動します
• クラッシュ時には指数バックオフで監視・再起動します（5→10→20→40→60 秒。稼働時間が 5 分を超えるとリセットされます）
• 再起動後も動作します。一度設定すれば、継続して実行されます

起動の確認

curl http://localhost:8765/health
# {"status":"ok","server":"remote-pc-mcp","version":"0.5.0"}

インストーラーを再実行するタイミング

install.bat／install.sh は冪等で、自己修復機能を備えています。次の場合はいつでも再実行してください。

• リポジトリを別のフォルダーに移動した
• Python を再インストールまたはアップグレードし、別のパスに変更した
• マシンを再構築し、自動起動を復元したい

日常的な運用では、意識する必要はありません。

再起動後

自動起動は、Windows にサインインしたときに実行されます。ロック画面のまま再起動した場合、誰かがログインするまでデーモンは起動しません。これは意図的な仕様です。再起動後に完全な無人運用を実現するため Windows の自動ログオンを有効にすると、マシンに物理的にアクセスできる人なら誰でもログイン済みのデスクトップを利用できてしまいます。リモート制御ツールにとって、これは適切なトレードオフではありません。

PC の前まで行かずに再起動後のデーモンを再び起動する必要がある場合は、Remote Desktop または Tailscale SSH でリモートからサインインしてください。ログインすると、スタートアップのショートカットが実行され、デーモンが起動します。

Linux は異なります。install.sh --linger は sudo loginctl enable-linger $USER を実行するため、ログオンしなくても systemd のユーザーユニットが再起動後も実行されます。systemd のユーザーサービスには、自動ログオンのようなセキュリティ上の問題はありません。対話型デスクトップへのアクセスを許可するのではなく、ユーザーのスコープ内で動作するデーモンを稼働させ続けるだけだからです。

アンインストール

# Windows
install.bat --uninstall

# Linux
./install.sh --uninstall

自動起動エントリーを削除し、実行中のサーバーとスーパーバイザーを停止します。

フォアグラウンドでの実行（開発用）

コンソール出力を表示し、自動起動を行わずに一度だけ実行するには、次のようにします。

python server.py

これだけです。特別なスクリプトは必要ありません。通常のスーパーバイズされたセットアップには、install.bat／install.sh を使用してください。

または PyPI からインストール

pip install remote-pc-mcp
remote-pc-mcp          # run the server in the foreground
remote-pc-mcp-daemon   # supervised: restarts the server on crash

pip でインストールすると、サーバーとスーパーバイザーのコマンドを利用できますが、自動起動は登録されません。サインイン時に自動起動するには、上記のリポジトリのクローンとインストールスクリプトの手順を使用してください。.env、ログ、.state/ は REMOTE_PC_MCP_HOME（デフォルト：作業ディレクトリ）に保存されます。

MCP クライアントへの追加

ほとんどの MCP クライアントでは同じ JSON スキーマを使用します。設定ファイルの場所だけが異なります。例：

{
  "mcpServers": {
    "remote-pc": {
      "type": "http",
      "url": "http://YOUR_PC_IP_OR_HOSTNAME:8765/mcp",
      "headers": {
        "Authorization": "Bearer your-long-random-token-here"
      }
    }
  }
}

設定ファイルの場所：

クライアント	設定ファイル
Claude Code	プロジェクトのルートにある .mcp.json（ユーザー全体に適用する場合は ~/.claude.json）
Claude Desktop	claude_desktop_config.json（Settings → Developer → Edit Config）
Cursor	.cursor/mcp.json
Cline / Continue / Windsurf	各クライアントに独自の MCP サーバーパネルがあります。そこに JSON を貼り付けてください
カスタムエージェント	エージェントが MCP サーバー定義を読み込む場所

Tailscale ユーザーは、URL に MagicDNS のホスト名を使用できます。

"url": "http://your-pc.tail12345.ts.net:8765/mcp"

クライアントを再起動（または再読み込み）してください。ツールが自動的に表示されます。"remote-pc" キーは単なるラベルなので、好きな名前を付けてください。

セキュリティ

shell_exec は、サーバーを起動したユーザーとして、ホスト上で任意のコマンドを実行します。これは意図的な仕様です。PC をリモート操作する際に、このサーバーを便利にする機能だからです。また、次の点にも注意してください。

• ベアラートークンは root と同等の権限を持つ認証情報です。 32 バイトの 16 進数トークンを生成し、.env（git の追跡対象外）だけに保存して、パスワードと同様に扱ってください。
• TLS とリバースプロキシ（nginx、Caddy、Cloudflare Tunnel）なしで、サーバーをパブリックインターネットに公開しないでください。
• Tailscale の使用を強くおすすめします。 Tailscale IP（.env で REMOTE_PC_MCP_HOST=100.x.x.x を設定）にバインドし、リスナーに tailnet 内のデバイスからのみアクセスできるようにしてください。
• REMOTE_PC_MCP_HOST=0.0.0.0 を設定した LAN 内限定の構成は、LAN 上のすべてのデバイスを信頼でき、強力なトークンを使用する場合には妥当です。信頼できないネットワークでは使用しないでください。

トークンの比較には secrets.compare_digest（一定時間での比較）を使用します。すべてのエラーメッセージはサニタイザーを通過し、クライアントに返される前に絶対パス、ホームディレクトリ、トークンが取り除かれます。

設定

REMOTE_PC_MCP_TOKEN を除き、すべての環境変数は省略可能です。

変数	デフォルト	説明
REMOTE_PC_MCP_TOKEN	(必須)	クライアントが提示する必要のあるベアラートークン
REMOTE_PC_MCP_HOST	0.0.0.0	バインドアドレス。到達範囲を制限するには、Tailscale の IP に設定します
REMOTE_PC_MCP_PORT	8765	リッスンポート
REMOTE_PC_MCP_ALLOWED_HOSTS	(空)	DNS リバインディング対策のための、カンマ区切りの許可リスト。空の場合は無効になります（デフォルトでは、tailnet 上で想定すべき脅威モデルに合いません）
REMOTE_PC_MCP_MAX_SHELL_TIMEOUT	600 (s)	呼び出しごとの shell_exec タイムアウト上限
REMOTE_PC_MCP_MAX_READ_BYTES	50 MB	read_file の上限
REMOTE_PC_MCP_MAX_WRITE_BYTES	50 MB	write_file の上限
REMOTE_PC_MCP_MAX_DOWNLOAD_BYTES	2 GB	download_file の上限
REMOTE_PC_MCP_SCREEN_MAX_EDGE	1568 (px)	take_screenshot 画像の長辺。0 にすると上限が無効になります
REMOTE_PC_MCP_SCREEN_MAX_PIXELS	1150000	take_screenshot 画像の総ピクセル数。0 にすると上限が無効になります

.env を変更した後は、新しい値を反映するためにサーバーを再起動してください。

# Windows: easiest path is just re-run the installer (idempotent)
install.bat --uninstall && install.bat

# Linux
systemctl --user restart remote-pc-mcp

ログとトラブルシューティング

リポジトリのルートにある 2 つのログファイルは、どちらも自動的にローテーションされます。

ファイル	内容	ローテーション
server.log	アプリケーションのイベントと uvicorn の起動／アクセスログ	10 MB × 5
daemon.log	スーパーバイザーのイベント（クラッシュ、再起動、バックオフ）	2 MB × 3

サーバーが応答しませんか？

# Is the listener up locally?
curl http://localhost:8765/health

# What's the supervisor seeing?
tail -f daemon.log

# Linux: full journal
journalctl --user -u remote-pc-mcp -f

# Windows: is the autostart registered?
explorer shell:startup    # look for remote-pc-mcp.lnk

サーバーの再起動後、MCP クライアントにツールが見つからないと表示されますか？

ストリーミング可能な HTTP トランスポートは、再起動によってクライアントが動作不能にならないよう設計されています。ただし、新しいサーバーを検知するには、クライアントがリクエストを送信する必要があります。まず、このサーバーのツールをどれか実行してください（例：エージェントに system_info を実行するよう依頼します）。クライアントが接続を再試行します。それでも失敗する場合は、クライアントで MCP サーバーに再接続するか（Claude Code：/mcp；Cursor：MCP パネルを更新）、クライアントを再起動してください。

プロセスが停止したままですか？ または、ポートがすでに使用中ですか？

# Windows
install.bat --uninstall && install.bat

# Linux
./install.sh --uninstall && ./install.sh

UI 操作用ツール

take_screenshot、click、move_mouse、type_text、press_key、scroll には対話型デスクトップセッションが必要です。

• Windows：ユーザーがログインし、画面のロックが解除されている必要があります。Session 0 で実行されるサービスはデスクトップにアクセスできません。スタートアップフォルダーを使ったインストールでは、デーモンがユーザーセッションで実行されるため、この条件を満たせます。
• Linux：X11 または Wayland セッションが必要です。スクリーンショットを撮るには、scrot、gnome-screenshot、または ImageMagick の import をインストールしてください。最も簡単なのは sudo apt install scrot です。

画面座標

ビジョンモデルが見るスクリーンショットは、画像の制限に収まるよう縮小されており、モデルが返す座標も縮小後の画像上のものです。そのため、take_screenshot はデスクトップ自体を縮小し、長辺を最大 REMOTE_PC_MCP_SCREEN_MAX_EDGE ピクセル、総ピクセル数を最大 REMOTE_PC_MCP_SCREEN_MAX_PIXELS にします。デフォルト値は Claude API の標準的な画像制限に合っているため、クライアント側で再度縮小されることはありません。結果として、JPEG 画像と、画像サイズ、縮尺、デスクトップのジオメトリ、ホスト上にあるフル解像度 PNG のパスを含む JSON ブロックが返されます。

click、move_mouse、scroll は、その画像上のピクセル単位で (x, y) を受け取ります。サーバーは各点を実際のデスクトップ上の位置に変換します。これには、プライマリーモニターの左側または上側にあり、デスクトップ座標が負になるモニターも含まれます。各呼び出しは、使用した desktop_x と desktop_y も返します。この変換はデスクトップの現在のサイズだけに依存するため、同じ画像サイズを使う限り、クライアントは先にスクリーンショットを撮らずにクリックできます。フル解像度の画像（デスクトップの 1 ピクセルにつき画像の 1 ピクセル）にするには、両方の上限を 0 に設定してください。座標の原点は引き続き画像の左上隅です。

Windows では、サーバーはモニターごとの DPI に対応して実行されます。そのため、各モニターの拡大率にかかわらず、キャプチャとマウス操作には物理ピクセルが使われます。

開発

プロジェクトの構成：

ファイル	役割
server.py	MCP サーバー — ツール、認証、トランスポート
daemon.py	スーパーバイザー — サーバーを起動し、クラッシュ時にはバックオフを挟んで再起動します
_logging.py	共通のログ設定 — アプリケーションと uvicorn のロガーでハンドラーを 1 つ共有します
_screen.py	画面領域：スクリーンショットのサイズと、ピクセルをデスクトップ上の座標に対応付ける方法
install.{bat,sh}	単一のエントリーポイント：デフォルトではインストールし、--uninstall で削除します

テスト

tests/ にある自己完結型のテストスイートは、エフェメラルトークンを使用して独立したサーバーを高いポート番号で起動し、すべてのツールを実行して、実行中にサーバーを再起動してもクライアントが締め出されないことを検証します。実行中の本番サーバーには一切触れません。

pip install -r requirements-dev.txt
python -m pytest tests/ -v

ライセンス

MIT