claude mcp addがPowerShell 5.1で失敗する: commandOrUrl欠落の原因

WindowsのPowerShell 5.1で claude mcp add を実行して error: missing required argument 'commandOrUrl' と返ってきたら、実行ファイルのパスを書き忘れたわけではない可能性があります。GitHubのissueの報告者は、区切りの -- がPowerShell 5.1に取り除かれ、Claude Code側に届いていないと見ています。

回避の第一候補は、-- を書かずに登録することです。ただし使える条件があります。この記事では、その条件と、PowerShell 7や claude mcp add-json に切り替える手順を並べます。

エラーメッセージは何を言っているのか

報告されている再現コマンドは次の形です。PowerShell 5.1で、環境変数を渡しつつ実行ファイルを登録します。

claude mcp add -s local my-server `
  -e SOME_VAR=value `
  -- C:\Users\<user>\bin\my-server.exe

結果は次のエラーです。

error: missing required argument 'commandOrUrl'

issueによると、同じコマンドはPowerShell 7では通り、-- がそのまま渡されます。つまり引数の綴りや引用符ではなく、シェルによる引数の加工が分かれ目です。

なぜ「足りない」と言われるのか

claude mcp add のstdio形式は claude mcp add [options] <name> -- <command> [args...] です。公式ドキュメントによると、-- はClaude自身のオプション(--transport、--env、--scope)と、サーバーを起動するコマンドを分ける区切りです。-- より後ろはサーバーにそのまま渡されます。

報告者の見立ては次のとおりです。PowerShell 5.1が -- を取り除くため、claude に届く引数列では実行ファイルのパスが区切りの位置に来ます。CLIは位置引数が1つ足りないと判断し、commandOrUrl が無いと答えます。実際には渡しているので、メッセージは原因を指していません。

issueには、原因がシェルだと分かるまでに約20分かかったとも書かれています。PowerShell 7で同じコマンドを実行して差を見たことが決め手になったそうです。

回避策1: -- を書かずに登録する

報告者が最初に挙げている手は、-- を外すことです。-- が必要なのは、起動するコマンド側に claude のオプションと紛らわしいフラグがあるときだけです。パスだけを渡す場合は区切りが無くても通る、と報告者は書いています。

ここで、公式ドキュメントの別の注記に気をつけます。--env は複数の KEY=value を受け取るため、--env の直後にサーバー名が来ると、名前も環境変数の組として読まれて拒否されるとあります。-e の直後に位置引数を置く並びは、同じ理由で実行ファイルのパスを環境変数として読ませる恐れがあります。issueのコマンドはこの形でした。

注記に沿って、-e を先頭に出し、間に --transport stdio を挟む並びにすると次のとおりです。

claude mcp add -e SOME_VAR=value --transport stdio my-server `
  C:\Users\<user>\bin\my-server.exe

MCPドキュメントのnpxの例は、--env を「サーバー名の後、-- の前」に置く形です。-- が使えるシェルなら、claude mcp add example --env API_KEY=your-key -- npx ... の並びで、--env の後ろは -- が止めてくれます。

右の列は、--env が複数の組を受け取るというドキュメントの説明からの推定で、issueに実行結果は載っていません。

この並びがPowerShell 5.1で通ることは、issueには書かれていません。その説明からの組み立てなので、手元で試して claude mcp get my-server で登録内容を確かめてください。

回避策2: PowerShell 7で実行する

PowerShell 7では -- がそのまま届きます(issueより)。公式ドキュメントの例をそのまま使いたいときは、この手が素直です。

pwsh
claude mcp add --transport stdio airtable `
  --env AIRTABLE_API_KEY=YOUR_KEY `
  -- npx -y airtable-mcp-server

issueは、PowerShell 5.1がWindowsの既定で入っている点を指摘しています。PowerShell 7は別途インストールが必要なので、会社の端末では導入できるかが先に問題になります。

回避策3: cmd経由で --% を使う

issueには cmd --% /c claude mcp add ... という形も挙がっています。--% はPowerShellに「以降を解析しない」と伝える記号で、-- をPowerShellの手前で消されずにcmdへ渡す狙いです。

cmd --% /c claude mcp add --transport stdio db -- C:\tools\db-server.exe

これもissueに書かれた案で、実行結果までは載っていません。--% の後ろでは %VAR% のようなcmd流の展開が起きる点を覚えておくと、環境変数を渡す場面で混乱しません。

回避策4: -- を使わない登録方法に切り替える

-- に頼らない道もあります。MCPドキュメントは、claude mcp add-json と .mcp.json でも設定を書けるとしています。JSONの中で command と args を別フィールドに持つので、区切り記号そのものが要りません。

claude mcp add-json my-server '{"command":"C:\\Users\\<user>\\bin\\my-server.exe","args":[]}'

MCPドキュメントには「JSONをシェルに合わせて正しくエスケープする」という注記があり、JSONをコマンドラインに載せる方法はシェルごとの引用符の扱いに左右されます。書き方はclaude mcp add-jsonでMCPサーバーをJSONのまま登録する手順にまとめています。環境変数を渡すときは、MCPドキュメントの例のように env フィールドをJSONに含めます。

claude mcp add-json my-server '{"type":"stdio","command":"C:\\Users\\<user>\\bin\\my-server.exe","args":[],"env":{"SOME_VAR":"value"}}'

issueの再現コマンドが -e SOME_VAR=value で渡していた値は、ここでは env に入ります。.mcp.json に直接書く場合も同じ形で、JSON文字列の中ではバックスラッシュを \\ と二重に書きます。

{
  "mcpServers": {
    "my-server": {
      "command": "C:\\Users\\<user>\\bin\\my-server.exe",
      "args": [],
      "env": { "SOME_VAR": "value" }
    }
  }
}

add-json は --scope project を付けるとチームで共有する設定になり、.mcp.json に書いた場合と同じ扱いです。.mcp.json のサーバーには承認の手順があるため、書いた直後に使えなくても、承認待ちかどうかを claude mcp get の状態で見ると切り分けられます。

引用符が不安なら、.mcp.json をエディタで直接書く方法が確実です。置き場所と読み込みはClaude Code MCP設定ガイドで扱っています。

どのサーバーなら -- を外せるのか

MCPドキュメントの例は npx -y airtable-mcp-server のように、起動コマンドに -y のようなフラグを含むものが中心です。-y は npx のフラグなので、-- を外すと claude 側のオプションとして解釈を試みられます。つまり、回避策1が効くのは実行ファイルのパスだけを渡す場合に限られます。

MCPドキュメントは、-- が無いとサーバーのフラグをClaude Code自身のオプションとして解釈しようとすると説明しています。表の2行目は -y について述べた説明からの推定です。3行目はドキュメントの説明をそのまま当てはめたものです。

Windowsの標準的なPowerShellに当てはめると、ドキュメントの例の大半は -- を含みます。issueも、組み込みの例を含む全ての例に -- が出てくる点を問題にしています。例をそのまま写しても通らない場面が出るのはこのためです。

切り分けの順番

この報告の確度

読む側が過信しないよう、issue自体の確度を書いておきます。

• 報告は、影響を受けた利用者の画面出力をもとにした二次情報で、報告者自身はmacOSで再現できていません
• 補足コメントに、Claude Code 2.1.251で起きたと記されています
• 発生したのがVS Code拡張経由かCLI単体かは、コメントで未確定とされています

-- を取り除くのがPowerShell 5.1のどの段階の挙動なのかは、issueには書かれていません。原因をシェルと見るのは報告者の推定です。報告では、期待する修正として、commandOrUrl が届かなかった場合にPowerShell 5.1と -- の欠落に触れるエラーを返すか、--help とMCPドキュメントに注意書きを足すことが挙げられています。

まとめ

PowerShell 5.1で commandOrUrl が足りないと言われたら、書いたパスを疑う前に、同じコマンドがPowerShell 7で通るかを見ます。通るなら -- の脱落が濃厚です。

起動コマンドが自前のフラグを持たないなら、-- を外し、--env の位置に気をつけて登録します。フラグを持つ場合はPowerShell 7、cmd経由、あるいはJSON登録に切り替えます。どの方法でも、登録後に claude mcp get <name> で内容を確かめると、取りこぼしに気づけます。