
mcp-remote exposed to OS command injection
mcp-remoteローカル(stdio)サーバーのみをサポートするMCPクライアントを、認証サポート付きでリモートMCPサーバーに接続します:
注:これは動作する概念実証(proof-of-concept)ですが、実験的 と見なすべきです。
これまでのところ、世の中のMCPサーバーの大半はstdioトランスポートを使用してローカルにインストールされています。これにはいくつかの利点があります:ユーザーが実行許可を付与しているため、クライアントとサーバーの両方が暗黙的に相互を信頼できます。APIキーなどの秘密情報の追加は環境変数を使って行え、マシンの外に出ることはありません。また、npx や uvx を利用することで、ユーザーは明示的なインストール手順を省略できます。
しかし、_ウェブに移せる_ソフトウェアのほとんどが実際に_ウェブに移された_のには理由があります:単一のデプロイですべてのユーザーに更新をプッシュできれば、バグの発見・修正や新機能の反復開発がはるかに簡単になるからです。
最新のMCP 認可仕様 により、ユーザーのラップトップでコードを実行すること_なく_、MCPサーバーを世界と共有する安全な方法が実現しました。いや、少なくとも、人気のあるMCP クライアント がすべて対応していれば、そうなっているはずです。大半はstdioのみ対応で、HTTP+SSEを_サポートしている_クライアントも、必要なOAuthフローにはまだ対応していません。
そこで登場するのが mcp-remote です。選択したMCPクライアントがリモートの認可済みサーバーをサポートするようになれば、これを削除できます。それまでの間は、この一行を追加して、使いたいMCPクライアントに合わせてください!
最も人気のあるMCPクライアント(Claude Desktop、Cursor、Windsurf)はすべて、以下の設定形式を使用します:
{
"mcpServers": {
"remote-example": {
"command": "npx",
"args": [
"mcp-remote",
"https://remote.mcp.server/sse"
]
}
}
}
認証をバイパスする場合、またはリモートサーバーへのすべてのリクエストにカスタムヘッダーを送信する場合は、--header CLI引数を渡します:
{
"mcpServers": {
"remote-example": {
"command": "npx",
"args": [
"mcp-remote",
"https://remote.mcp.server/sse",
"--header",
"Authorization: Bearer ${AUTH_TOKEN}"
],
"env": {
"AUTH_TOKEN": "..."
}
},
}
}
注: Cursor と Claude Desktop(Windows)には、npx を呼び出す際に args 内のスペースがエスケープされず、値が壊れてしまうバグがあります。次のようにして回避できます:
{
// rest of config...
"args": [
"mcp-remote",
"https://remote.mcp.server/sse",
"--header",
"Authorization:${AUTH_HEADER}" // note no spaces around ':'
],
"env": {
"AUTH_HEADER": "Bearer <auth-token>" // spaces OK in env vars
}
},
npx でエラーが発生する場合は、mcp-remote パッケージのインストールを自動承認するために、最初の引数として -y を追加することを検討してください。 "command": "npx",
"args": [
"-y"
"mcp-remote",
"https://remote.mcp.server/sse"
]
npx に常に mcp-remote の最新版を確認させるには、@latest フラグを追加します: "args": [
"mcp-remote@latest",
"https://remote.mcp.server/sse"
]
mcp-remote が待ち受けるポート(デフォルトは 3334)を変更するには、サーバーURLの後に追加の引数を指定します。指定したポートが利用できない場合、開いているポートがランダムに選択されることに注意してください。 "args": [
"mcp-remote",
"https://remote.mcp.server/sse",
"9696"
]
mcp-remote が登録するホスト(デフォルトは localhost)を変更するには、--host フラグを追加します。 "args": [
"mcp-remote",
"https://remote.mcp.server/sse",
"--host",
"127.0.0.1"
]
--allow-http フラグを追加します。注:これは、トラフィックが傍受されない安全なプライベートネットワークでのみ使用してください。 "args": [
"mcp-remote",
"http://internal-service.vpc/sse",
"--allow-http"
]
--debug フラグを追加します。これにより、認証プロセス、接続、トークン更新に関するタイムスタンプ付きの詳細なログが ~/.mcp-auth/{server_hash}_debug.log に書き込まれます。 "args": [
"mcp-remote",
"https://remote.mcp.server/sse",
"--debug"
]
--enable-proxy フラグを追加します。有効にすると、mcp-remote は一般的な環境変数(例:HTTP_PROXY、HTTPS_PROXY、NO_PROXY)からプロキシ設定を使用します。 "args": [
"mcp-remote",
"https://remote.mcp.server/sse",
"--enable-proxy"
],
"env": {
"HTTPS_PROXY": "http://127.0.0.1:3128",
"NO_PROXY": "localhost,127.0.0.1"
}
--ignore-tool フラグを追加します。これにより、指定したパターンに一致するツールが tools/list レスポンスから除外され、tools/call リクエストもブロックされます。* によるワイルドカードパターンをサポートします。 "args": [
"mcp-remote",
"https://remote.mcp.server/sse",
"--ignore-tool",
"delete*",
"--ignore-tool",
"remove*"
]
複数の --ignore-tool フラグを指定して、さまざまなパターンを無視できます。例:
delete* - "delete" で始まるすべてのツールを無視します(例:deleteTask、deleteUser)*account - "account" で終わるすべてのツールを無視します(例:getAccount、updateAccount)exactTool - 「exactTool」という正確な名前のツールのみを無視します30 秒)を変更するには、秒単位の値を指定して --auth-timeout フラグを追加します。これは、サーバー側の認証プロセスに時間がかかる場合に便利です。 "args": [
"mcp-remote",
"https://remote.mcp.server/sse",
"--auth-timeout",
"60"
]
MCP Remote は、MCPサーバーへの接続時にさまざまなトランスポート戦略をサポートしています。これにより、Server-Sent Events(SSE)とHTTPトランスポートのどちらを使用するか、またどの順序で試行するかを制御できます。
--transport フラグでトランスポート戦略を指定します:
npx mcp-remote https://example.remote/server --transport sse-only
利用可能な戦略:
http-first(デフォルト):まずHTTPトランスポートを試行し、HTTPが404エラーで失敗した場合はSSEにフォールバックしますsse-first:まずSSEトランスポートを試行し、SSEが405エラーで失敗した場合はHTTPにフォールバックしますhttp-only:HTTPトランスポートのみを使用し、サーバーがサポートしていない場合は失敗しますsse-only:SSEトランスポートのみを使用し、サーバーがサポートしていない場合は失敗しますMCP Remote は、mcp-remote のデフォルトを使用する代わりに、静的なOAuthクライアントメタデータを提供することをサポートしています。 これは、特定のクライアント/ソフトウェアIDやスコープを期待するOAuthサーバーに接続する場合に便利です。
--static-oauth-client-metadata フラグを使用して、クライアントメタデータをJSON文字列または @ 接頭辞付きのファイルパスとして指定します:
npx mcp-remote https://example.remote/server --static-oauth-client-metadata '{ "scope": "space separated scopes" }'
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-metadata '@/Users/username/Library/Application Support/Claude/oauth_client_metadata.json'
仕様 に従い、 サーバーには OAuth動的クライアント登録 のサポートが推奨されていますが、必須ではありません。
このようなサーバーに対して、MCP Remote は代わりに静的なOAuthクライアント情報を提供することをサポートしています。 これは、事前登録されたクライアントを必要とするOAuthサーバーに接続する場合に便利です。
--static-oauth-client-info フラグを使用して、クライアント情報をJSON文字列または @ 接頭辞付きのファイルパスとして指定します:
export MCP_REMOTE_CLIENT_ID=xxx
export MCP_REMOTE_CLIENT_SECRET=yyy
npx mcp-remote https://example.remote/server --static-oauth-client-info "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
# uses node readfile, so you probably want to use absolute paths if you're not sure what the cwd is
npx mcp-remote https://example.remote/server --static-oauth-client-info '@/Users/username/Library/Application Support/Claude/oauth_client_info.json'
Claude Desktop にMCPサーバーを追加するには、以下の場所にある設定ファイルを編集する必要があります:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonまだ存在しない場合は、Settings > Developer で有効にする必要があるかもしれません。
設定ファイルの変更を反映するには、Claude Desktop を再起動します。 再起動後、入力ボックスの右下隅にハンマーアイコンが表示されるはずです。
公式ドキュメント。設定ファイルは ~/.cursor/mcp.json にあります。
バージョン 0.48.0 以降、Cursor は認証なしのSSEサーバーを直接サポートしています。MCPサーバーが公式のMCP OAuth認可プロトコルを使用している場合は、引き続き "command" サーバーを追加して mcp-remote を呼び出す必要があります。
公式ドキュメント。設定ファイルは ~/.codeium/windsurf/mcp_config.json にあります。
有効なOAuthクライアントとして動作することを含む、リモートMCPサーバーの構築とデプロイの手順については、以下のリソースを参照してください:
特に、以下を参照してください:
agents フレームワークを使用して McpAgent を定義するためこれらのサーバーのテストについて詳しくは、以下も参照してください:
共有したいリソースを他にもご存知ですか?このReadmeに追加してPRを送ってください!
~/.mcp-auth ディレクトリをクリアするmcp-remote はすべての認証情報を ~/.mcp-auth(または MCP_REMOTE_CONFIG_DIR が指す場所)に保存します。問題が続く場合は、次を実行してみてください:
rm -rf ~/.mcp-auth
その後、MCPクライアントを再起動します。
インストールされているNodeのバージョンが 18以上 であることを確認してください。Claude Desktop は、他の場所に新しいバージョンがインストールされていても、システムのNodeバージョンを使用します。
claude_desktop_config.json を変更するときは、Claudeを完全に再起動すると役立つことがあります
VPNの背後にいる場合は問題が発生する可能性があります。NODE_EXTRA_CA_CERTS 環境変数を設定してCA証明書ファイルを指すようにしてみてください。claude_desktop_config.json を使用している場合、次のようになります:
{
"mcpServers": {
"remote-example": {
"command": "npx",
"args": [
"mcp-remote",
"https://remote.mcp.server/sse"
],
"env": {
"NODE_EXTRA_CA_CERTS": "{your CA certificate file path}.pem"
}
}
}
}
tail -n 20 -F ~/Library/Logs/Claude/mcp*.logtail -n 20 -f "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log"Get-Content "C:\Users\YourUsername\AppData\Local\Claude\Logs\mcp.log" -Wait -Tail 20複雑な問題、特にトークン更新や認証の問題をトラブルシューティングするには、--debug フラグを使用します:
"args": [
"mcp-remote",
"https://remote.mcp.server/sse",
"--debug"
]
これにより、接続と認証プロセスの各ステップに関するタイムスタンプ付きの完全な情報を含む詳細なログが ~/.mcp-auth/{server_hash}_debug.log に作成されます。トークン更新の問題、ラップトップのスリープ/復帰の問題、認証の問題が発生した場合は、サポートを求める際にこれらのログを提供してください。
/callback URLによって返される次のエラーが発生した場合:
Authentication Error
Token exchange failed: HTTP 400
rm -rf ~/.mcp-auth を実行して、ローカルに保存された状態とトークンをクリアできます。
コマンドラインで次を実行します(MCPサーバーからではなく):
npx -p mcp-remote@latest mcp-remote-client https://remote.mcp.server/sse
これにより、認可フロー全体が実行され、リモートURLのツールとリソースの一覧表示が試行されます。rm -rf ~/.mcp-auth を実行した後にこれを試して、古い認証情報が問題かどうかを確認してください。そうでない場合は、MCPクライアントのログよりも、これらのログで問題がより明確になるはずです。