universal-host-manager-mcp

Universal Host Manager MCP

ChatGPT や Claude などの MCP クライアントを通じて Linux または macOS のホストを管理する、クロスプラットフォーム対応の Model Context Protocol サーバーです。

FastMCP の Streamable HTTP トランスポート、Auth0 OAuth、アクセス範囲を制限したファイルツール、出力制限、コマンドタイムアウトを使用します。

注意

このプロジェクトでは任意のシェルコマンドを実行できます。認証によって使用できるユーザーを制限できますが、コマンドが無害になるわけではありません。デプロイする前に SECURITY.md をお読みください。

機能

• Linux および macOS に対応
• Streamable HTTP エンドポイント
• Auth0 OAuth との統合
• MCP_WORKSPACE_DIR 内に制限されたファイルの読み取り、書き込み、ディレクトリ一覧表示
• 設定可能なコマンドタイムアウトと出力の切り詰め
• ファイルサイズ制限とデコード時のフォールバック
• 認証が設定されていない場合、安全側に停止する起動処理
• systemd と launchd のサービス設定例

ツール

ツール	パラメーター	目的
run_command	command: str, timeout: int	ワークスペースを作業ディレクトリとして、任意のシェルコマンドを実行します
read_file	path: str	ワークスペース内のテキストファイルを読み取ります
write_file	path: str, content: str	ワークスペース内に UTF-8 テキストを書き込みます
list_dir	path: str = "."	ワークスペース内のディレクトリの一覧を表示します
system_metrics	なし	ディスク、メモリ、上位プロセスの情報を報告します

ワークスペースの境界が適用されるのはファイルツールです。run_command はサンドボックス化されません。コマンドには、サービスの OS ユーザーが持つすべての権限が適用されます。

必要条件

• Python 3.10+
• Linux または macOS
• リモート利用には Auth0 アカウント
• リモート MCP クライアントには HTTPS エンドポイント

インストール

PyPI（推奨）

pip install universal-host-manager-mcp

次に、uhm-setup を実行して .env を生成します。詳しくは下記の 設定 をご覧ください。

uv / pipx

プロジェクト環境を汚さずにインストールするには、次のようにします。

uvx --from universal-host-manager-mcp uhm-setup

一時的な環境にインストールされ、セットアップウィザードが実行されて、現在のディレクトリに .env が作成されます。以降は、サーバー自体も同じ方法で実行します。uvx universal-host-manager-mcp

ソースからのインストール（開発用）

git clone https://github.com/Abktya/universal-host-manager-mcp.git
cd universal-host-manager-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

次に、uhm-setup を実行して .env を生成します。詳しくは下記の 設定 をご覧ください。

設定

最も簡単な方法は、サーバーと一緒にインストールされる対話型セットアップウィザードを使うことです。

uhm-setup

設定を保存するディレクトリから実行してください。サーバーが .env を見つけられるように、後でサーバーを同じディレクトリから起動する必要があります。

最初のテストでは、1 — ローカルのみのテストを選択してください。Enter キーを押してポート 8765 を受け入れます。ポートの入力欄では y や n ではなく、数値を指定します。このモードでは、次のようになります。

• デフォルトで個別の workspace ディレクトリが作成されます。
• 127.0.0.1 のみでリッスンするため、他のコンピューターから接続できません。
• ドメイン、トンネル、Auth0 アカウントは不要です。
• ローカルテストに限り、認証なしのアクセスが有効になります。

ウィザードでは、リモートで使用するための Cloudflare Tunnel、ngrok の静的ドメイン、既存の HTTPS URL も選択できます。リモートモードでは Auth0 が必要です。Auth0 をスキップした場合、誤解を招く、使用できない設定が書き込まれることはありません。ドメインと URL が検証され、その後、既存のファイルがあれば最初に .env.bak にバックアップしてから、アクセス権限を 600 に設定して .env が書き込まれます。

仮想環境が有効な場合は、両方のコマンドをその環境経由でインストールして実行してください。

python -m pip install universal-host-manager-mcp
uhm-setup
universal-host-manager-mcp

macOS/Linux で、コマンドが有効な環境に属していることを確認するには、次のようにします。

command -v uhm-setup
command -v universal-host-manager-mcp
python -m pip show universal-host-manager-mcp

最初の 2 つのパスは、通常 .venv/bin 内を指しているはずです。仮想環境が有効なのに /opt/homebrew/bin を指している場合は、python -m pip install universal-host-manager-mcp を使って再インストールしてください。

手動で設定する場合は、明示的に制限したワークスペースを指定して .env ファイルを作成します（ソースからインストールした場合は .env.example をコピーしてください）。

HOST=127.0.0.1
PORT=8765
MCP_BASE_URL=https://mcp.example.com
MCP_WORKSPACE_DIR=/home/youruser/workspace

AUTH0_DOMAIN=your-tenant.eu.auth0.com
AUTH0_CLIENT_ID=replace_me
AUTH0_CLIENT_SECRET=replace_me
AUTH0_AUDIENCE=https://mcp.example.com/

.env をコミットしないでください。

Auth0 のセットアップ

このプロジェクトでは、FastMCP の Auth0Provider による固定クライアント OAuth 連携を使用します。

1. auth0.com を開いてアカウントを作成し、Auth0 ダッシュボードを開きます。

2. Applications → APIs → Create API に移動します。

3. Identifier（オーディエンス）として、MCP の公開 URL を指定します。例：https://mcp.example.com/。署名アルゴリズムは RS256 のままにします。

4. Applications → Applications → Create Application に移動し、名前を入力して Regular Web Application を選択し、作成します。

5. Application Ownership を First-party に設定します。Application > API Access を開き、作成した API を選択して User-delegated Access を有効にします。

6. Auth0 の Integrate into your application ページで、.env ブロックの上にある Copy をクリックします。ウィザードでは、クリップボードまたは貼り付けたブロックから AUTH0_DOMAIN、AUTH0_CLIENT_ID、AUTH0_CLIENT_SECRET をインポートできます。Auth0 に MASKED と表示される場合は、アプリケーションの Settings タブで実際の Client Secret を表示してコピーしてください。マスクされたシークレットは拒否されます。

7. ウィザードで入力を求められたら、API の Identifier を AUTH0_AUDIENCE にコピーします。Auth0 のアプリケーション用 .env ブロックには API オーディエンスが含まれていないため、これは意図的に別の項目になっています。

8. Auth0 アプリケーションの Settings で、MCP サーバーの公開オリジン（/mcp を除く）を以下のように設定します。

   Auth0 フィールド	値
   Application Ownership	First-party
   Application Type	Regular Web Application
   Application Login URI	空欄のままにします
   Allowed Callback URLs	https://mcp.example.com/auth/callback
   Allowed Logout URLs	https://mcp.example.com
   Allowed Web Origins	https://mcp.example.com
   Allowed Origins (CORS)	https://mcp.example.com
   Allow Cross-Origin Authentication	オフ／無効
   Cross-Origin Verification Fallback URL	空欄のままにします
   API Identifier / Audience	https://mcp.example.com/
   Signing Algorithm	RS256
   Application > API Access	作成した API の User-delegated Access を有効化
   MCP endpoint（Auth0 ではなく AI クライアントに入力）	https://mcp.example.com/mcp

9. Auth0 アプリケーションの設定を保存してから、ウィザードを実行します。Client Secret を共有したり、.env を Git にコミットしたりしないでください。

上記のコールバックは、FastMCP の固定された上流コールバックです。Auth0 に Claude、ChatGPT、Grok のコールバック URL を設定しないでください。これらの製品は下流の MCP クライアントであり、FastMCP が MCP クライアントの登録時にそれぞれのリダイレクト URI を個別に検証します。各製品を https://mcp.example.com/mcp に接続してください。

Auth0 の Python クイックスタートには、AUTH0_SECRET、APP_BASE_URL、PORT、Flask のサンプルコードも記載されています。これらは Auth0 の単独サンプル Web アプリケーション用であり、この MCP サーバーでは使用されません。コピーしたブロックをインポートする際、ウィザードはこれらを安全に無視します。

クライアントに関する注意事項：

• ChatGPT は、CIMD と DCR による MCP OAuth クライアント登録に対応しています。サーバーでは https://chatgpt.com/connector_platform_oauth_redirect が許可されています。ChatGPT の開発者モードで、公開 /mcp エンドポイントを追加してください。
• Claude のカスタムコネクターは公開 /mcp エンドポイントを受け付け、接続時に OAuth を開始します。
• Grok のカスタムコネクターは、公開アクセス可能な MCP サーバー URL を受け付け、必要な認証を完了します。Grok が利用できるかどうかは、現在の Grok プランやワークスペースの制御設定によって異なる場合があります。

FastMCP は、Auth0MCPProvider による Auth0 ネイティブの MCP／DCR 経路にも対応しています。このリポジトリでは現在、手動管理の固定クライアント Auth0Provider 経路を使用しています。

実行

universal-host-manager-mcp

（.venv を有効化したソースチェックアウトから実行しても同じように動作します。コンソールスクリプトは pip install -e . によってインストールされます。）

デフォルトのポートを使用する場合、Streamable HTTP エンドポイントは次のとおりです。

http://127.0.0.1:8765/mcp

Auth0 を使用せず、意図的にローカル限定でテストする場合：

ALLOW_INSECURE_NO_AUTH=true universal-host-manager-mcp

インターネットからアクセス可能なエンドポイントでは、非セキュアモードを使用しないでください。

サーバー（リモートモードの場合はトンネルも）の起動後、次のコマンドで確認してください。

curl -i https://mcp.example.com/mcp
# Expected without a token: HTTP 401

curl -i https://mcp.example.com/.well-known/oauth-authorization-server
# Expected: HTTP 200

サーバーとトンネルは両方とも起動したままにしておく必要があります。どちらかを終了すると、トンネル経由のエンドポイントは利用できなくなります。

Cloudflare Tunnel

cloudflared をインストールして認証し、名前付きトンネルを作成します。

cloudflared tunnel login
cloudflared tunnel create universal-host-manager-mcp
cloudflared tunnel route dns universal-host-manager-mcp mcp.example.com

~/.cloudflared/config.yml を作成します。

tunnel: YOUR_TUNNEL_ID
credentials-file: /home/youruser/.cloudflared/YOUR_TUNNEL_ID.json

ingress:
  - hostname: mcp.example.com
    service: http://127.0.0.1:8765
  - service: http_status:404

検証して実行します。

cloudflared tunnel ingress validate
cloudflared tunnel run universal-host-manager-mcp

universal-host-manager-mcp と cloudflared の両方を起動したままにしてください。どちらかのプロセスを終了すると、公開エンドポイントがオフラインになります。セットアップウィザードでは、実行可能な uhm-enable-autostart.sh インストーラーを作成できます。このインストーラーは、両方のプロセス用に Linux の systemd-user サービスまたは macOS の LaunchAgents を作成し、実行するコマンドを 1 つ表示します。

リモート MCP URL は次のとおりです。

https://mcp.example.com/mcp

MCP_BASE_URL=https://mcp.example.com を設定してください。MCP_BASE_URL に /mcp を含めないでください。

ドメインをお持ちでない場合：ngrok の無料静的ドメインを使用する

Auth0 OAuth には安定した HTTPS URL が必要ですが、そのためにドメインを所有する必要はありません。再起動のたびに変わる ngrok の以前のランダム URL や、同じ問題がある Cloudflare のログイン不要なクイックトンネルとは異なり、ngrok の無料プランには、変更されないアカウントごとに 1 つの静的サブドメインが無料で含まれています。

1. ngrok.com で無料アカウントを作成します。macOS では brew install ngrok/ngrok/ngrok でインストールします。Ubuntu では sudo snap install ngrok を使用します。その他の Linux ディストリビューションでは、ngrok 公式のダウンロード手順を利用できます。

2. ngrok の authtoken ページを開き、トークンをコピーして、次のコマンドを実行します。

   ngrok config add-authtoken YOUR_NGROK_TOKEN
   

   ドメイン ID ではなく、authtoken を使用してください。絶対に共有しないでください。公開された場合は、ダッシュボードでリセットしてください。

3. ngrok ダッシュボードから無料の静的ドメインを取得します（Domains → New Domain）。your-name.ngrok-free.dev のようなドメインが取得できます。

4. .env があるディレクトリから universal-host-manager-mcp を起動します。

5. 2 つ目のターミナルで、トンネルを起動します。

   ngrok http --url=your-name.ngrok-free.dev 8765
   

   両方のプロセスを起動したままにしておく必要があります。 どちらかを終了すると、公開エンドポイントがオフラインになります。ウィザードでは、両方のプロセス用に Linux の systemd-user サービスまたは macOS の LaunchAgents をインストールする uhm-enable-autostart.sh を作成できます。

6. .env で MCP_BASE_URL=https://your-name.ngrok-free.dev を設定します（HOST=127.0.0.1 はそのままにしてください。サーバーがループバックでのみリッスンしている間、ngrok がローカルポートに転送します）。

7. Auth0 で、アプリケーションのコールバック URL に https://your-name.ngrok-free.dev/auth/callback を設定します。Web オリジンとログアウト URL には https://your-name.ngrok-free.dev を設定してください（Auth0 の設定を参照）。

リモート MCP URL は次のとおりです。

https://your-name.ngrok-free.dev/mcp

個人利用や少数のクライアントでの利用に適しています。本番環境で大規模なトラフィックを扱う場合、ngrok の無料プランには接続数と帯域幅の制限があります。制限を超える場合は、料金ページを確認するか、上記のドメインベースの Cloudflare Tunnel の設定に切り替えてください。

AWS EC2 へのデプロイ

以下の手順では、サーバーを EC2 インスタンスにデプロイし、リモート MCP クライアントから安全にアクセスできるようにします。

1. インスタンスを起動する

• AMI：Ubuntu 24.04 LTS（以下のコマンドは Ubuntu／apt 用です。Amazon Linux 2023 では代わりに sudo dnf install -y python3-pip を使用してください）
• インスタンスタイプ：一般的な管理ワークロードであれば、t3.micro／t3.small で十分です
• セキュリティグループ：自分の IP からのインバウンド SSH（22） のみを許可します。以下の Cloudflare Tunnel オプションを使用する場合、その他のインバウンドポートは必要ありません。

2. サーバーをインストールする

インスタンスに SSH 接続してから、PyPI からインストールします。

sudo apt update && sudo apt install -y python3-pip python3-venv
python3 -m venv ~/uhm-venv
source ~/uhm-venv/bin/activate
pip install universal-host-manager-mcp

3. 設定

mkdir -p ~/workspace
cat > ~/.env << 'EOF'
HOST=127.0.0.1
PORT=8765
MCP_BASE_URL=https://mcp.example.com
MCP_WORKSPACE_DIR=/home/ubuntu/workspace

AUTH0_DOMAIN=your-tenant.eu.auth0.com
AUTH0_CLIENT_ID=replace_me
AUTH0_CLIENT_SECRET=replace_me
AUTH0_AUDIENCE=https://mcp.example.com/
EOF
chmod 600 ~/.env

HOST=127.0.0.1 のままにしてください。サーバーがインスタンスのパブリックインターフェースで直接リッスンすることは避けてください。インターネットへの公開は、インスタンス自身のポートを開放するのではなく、以下で説明するトンネルまたはロードバランサーでのみ行います。

4. ネットワーク：インスタンスへの HTTPS URL を取得する

Auth0 OAuth には HTTPS が必要です。次のいずれかを選択してください。

オプション A — Cloudflare Tunnel（推奨、インバウンドポート不要）

EC2 インスタンスから、上記の Cloudflare Tunnel セクションの手順を実行します。トンネルはアウトバウンドのみの接続なので、SSH 以外のインバウンドポートを開放する必要はなく、Elastic IP も不要です。インスタンスを NAT ゲートウェイの背後にあるプライベートサブネットに配置することもできます。

ドメインをお持ちでない場合は、代わりに上記のドメインがない場合：ngrok の無料静的ドメインを使用するの手順を EC2 インスタンスから実行してください。同じくアウトバウンドのみでインバウンドポートは不要です。

オプション B — ACM 証明書を使用した Application Load Balancer

• ドメインの ACM 証明書をリクエストして、ALB にアタッチします
• ALB に HTTPS（443）リスナーを作成し、インスタンスの PORT に転送します
• インスタンスのセキュリティグループでは、インバウンドの PORT をALB のセキュリティグループからのみ許可します。0.0.0.0/0 からは決して許可しないでください
• DNS を ALB に向け、MCP_BASE_URL にそのホスト名を設定します

5. systemd サービスとして実行する

同梱のユニットを再利用します（以下のバックグラウンドサービスを参照）。

sudo cp examples/mcp-manager.service /etc/systemd/system/
# edit User=, WorkingDirectory=, EnvironmentFile= and ExecStart= to point at
# ~/uhm-venv/bin/universal-host-manager-mcp and ~/.env
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-manager
sudo systemctl status mcp-manager --no-pager

6. Elastic IP

どちらのネットワークオプションでも必要ありません。Cloudflare Tunnel はインスタンスのアドレスにかかわらずアウトバウンド接続を行い、ALB はインスタンス ID またはプライベート IP でターゲットを登録するため、こちらも不要です。このインスタンスに固定パブリック IP が必要な別の構成要素がある場合にのみ、Elastic IP を追加してください。

ChatGPT と Claude

クライアントの MCP／コネクター設定に、パブリックな Streamable HTTP URL を追加します。

https://mcp.example.com/mcp

クライアントが認証フローを開いたら、Auth0 にサインインしてください。設定画面やサポートされるコネクターオプションは変更されることがあるため、従来の SSE に関する手順ではなく、最新のクライアントドキュメントに従ってください。

複数のクライアントを同じ実行中の HTTP サーバーに接続できます。各クライアントは個別に認証されます。別のサーバープロセスやポートは必要ありません。

バックグラウンドサービス

Linux systemd

同梱のユニットをコピーして編集します。

sudo cp examples/mcp-manager.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-manager
sudo systemctl status mcp-manager --no-pager

この例では systemd のセキュリティ強化ディレクティブを使用しています。MCP サーバーが実際に必要とするリソースに合わせて、ReadWritePaths、ProtectHome、ユーザー、パス、権限を調整してください。

macOS launchd

examples/com.user.mcpmanager.plist のパスを編集してから、次を実行します。

cp examples/com.user.mcpmanager.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.user.mcpmanager.plist
launchctl kickstart -k gui/$(id -u)/com.user.mcpmanager

macOS リモートアクセス準備テスト

リモートの macOS インストールでは、uhm-setup の最後に次の確認が表示されます。

Run macOS Remote Access Readiness Test now? [Y/n]

Mac のそばにいる状態でこれを実行してください。リモートで使用する予定の機能だけを選択します。ウィザードでは、ワークスペースの読み書きアクセスをテストし、読み取り専用の Google Chrome Automation リクエストを実行し、保護されたファイル、アクセシビリティ、画面収録のための macOS の「プライバシーとセキュリティ」設定画面を正確に開けます。アプリケーションや通常の URL を開くだけで、追加のプライバシー許可が必要になることはありません。

macOS では、TCC のプライバシー確認プロンプトをユーザーが承認する必要があります。ウィザードがこれを回避したり、クリックしたりすることはありません。サーバーの実行ファイルの正確なパスを表示し、選択した各許可の承認を求め、準備状況のレポートを出力します。無人で使用する前に許可を設定していない場合、後続のリモートタスクで、Mac の前にいる誰かによる対応が必要なダイアログが表示され、処理が止まることがあります。

フルディスクアクセス、Automation、アクセシビリティなどの許可は、対象となる実行ファイルやインストールパスに紐付けられることがあります。仮想環境の再作成、Python バージョンの切り替え、別の場所への再インストールを行うと、再度承認が必要になる場合があります。プライバシー許可を変更した後は、リモートで使用する前に MCP LaunchAgent を再起動してください。

設定

変数	デフォルト	説明
HOST	127.0.0.1	リッスンアドレス
PORT	8765	リッスンポート
MCP_BASE_URL	ローカル URL	/mcp を含まない、公開 OAuth ベース URL
MCP_WORKSPACE_DIR	ユーザーのホームディレクトリ	ファイルツールとコマンドの作業ディレクトリの境界
MAX_OUTPUT_CHARS	64000	ツール出力で返される文字数の上限
DEFAULT_CMD_TIMEOUT	300	コマンドのデフォルトタイムアウト（秒）
MAX_CMD_TIMEOUT	1800	設定可能なコマンドタイムアウトの上限
MAX_READ_BYTES	5000000	read_file で読み取るファイルサイズの上限
MAX_WRITE_BYTES	5000000	write_file で書き込むコンテンツサイズの上限
LOG_LEVEL	INFO	Python のログレベル
LOG_COMMANDS	false	タイムアウトだけでなく、run_command のコマンドテキスト（シークレットが含まれる場合があります）をログに記録します
FASTMCP_CHECK_FOR_UPDATES	off（設定しない場合は強制的にこの値になります）	起動時に FastMCP 独自の PyPI 更新チェックを行います
ALLOW_INSECURE_NO_AUTH	false	ローカル開発用の明示的な認証バイパス

テスト

pip install -e ".[dev]"
pytest tests/

CI では、メジャーバージョン間で @mcp.tool() の戻り値の型が変更されており、テストでは小規模なバージョン非依存ヘルパー（tests/conftest.py::call_tool）を介してツールを呼び出し、3 つすべてのバージョンを対象にしているため、プッシュのたびに fastmcp 2.13、3.x、4.x に対してテストスイートを実行します（上のバッジを参照）。

ダウンロード

Git でクローンします。

git clone https://github.com/Abktya/universal-host-manager-mcp.git

または、GitHub で Code → Download ZIP を選択してください。

ライセンス

MIT