mcp-installer

MCP Installer

概要

CLI を優先するワークフローと、安全な手動での代替手段を使用して、複数のクライアントと OS に MCP サーバーの設定をインストールします。

ワークフロー

1) 入力を収集する

• 対象のクライアント ID と OS を特定します。対応クライアントの一覧と既知のパスは references/clients.md を参照してください。
• MCP サーバーの定義（名前 -> 設定オブジェクト）を収集し、既存の項目を上書きするかどうかを決めます。
• 提供された MCP 設定にシークレットが含まれている場合（key、token、apiKey、accessToken、secret、password、Authorization などのフィールド、または *_KEY、*_TOKEN などの環境変数）、インストールを中断し、まずユーザーに値を取得して提供するよう依頼してください。ユーザーが必要な認証情報を用意できたことを確認した場合（またはプレースホルダーをインストールして後で入力することを希望した場合）に限り、続行してください。

2) （対応している場合）@smithery/cli を優先する

• npx @smithery/cli --help と npx @smithery/cli install --help を実行し、正確な構文を確認します。
• クライアント ID に対して CLI のインストールフローを使用します。CLI がクライアントを受け付けない場合、または失敗した場合は、手動編集に切り替えてください。

3) 手動でインストールする（JSON 設定での代替手段）

• 設定ファイルのパスを特定します（references/clients.md を参照）。不明な場合は、標準的な設定ディレクトリで mcp.json、mcp_config.json、claude_desktop_config.json、cline_mcp_settings.json などのファイルを検索します。
• 既存の JSON を読み込み、トップレベルに mcpServers オブジェクトがあることを確認します。
• サーバーをマージします。新しい名前を追加し、override が true の場合は既存の名前を置き換え、その他のキーはすべて保持します。
• JSON は 2 スペースのインデントで書き込みます。

設定例：

{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "example-mcp@latest"],
      "env": {}
    }
  }
}

4) 検証とトラブルシューティング

• クライアントを再起動し、MCP サーバーが表示されることを確認します。
• macOS で書き込みに失敗した場合は、フルディスクアクセスを許可するよう案内し、書き込み前にクライアントアプリが終了していることを確認します。
• CLI 専用クライアント（例：claude-code）の場合は、クライアント CLI のヘルプで MCP のインストール／設定コマンドを確認します。
• Trae／Trae-CN のインストールが権限やその他のエラーで失敗した場合は、ディープリンクを生成して代替手段として提示します。

5) Trae のディープリンクによる代替手段

trae または trae-cn がディスクに書き込めない場合は、ユーザーが Trae で開けるスキーマリンクを生成します。

• trae：trae://trae.ai-ide/mcp-import?type=${TYPE}&name=${NAME}&config=${BASE64_ENCODED_CONFIG}
• trae-cn：trae-cn://trae.ai-ide/mcp-import?type=${TYPE}&name=${NAME}&config=${BASE64_ENCODED_CONFIG}

ルール：

• TYPE は MCP のトランスポートタイプです（例：streamable-http）。
• NAME は Trae に表示されるサーバー名です。
• config は、そのサーバーの JSON 設定オブジェクトを Base64 エンコードしたものです（空白なし、UTF-8 バイト列）。

参考資料

• クライアント ID、エイリアス、既知の設定パスについては references/clients.md を参照してください。