MCP Server for Bring! Shopping

Bring! ショッピング用 MCP サーバー

このプロジェクトは、Bring! ショッピングリスト API の機能を公開するローカルの Model Context Protocol（MCP）サーバーを TypeScript で実装しています。Claude Desktop などのアプリケーションが、標準化された MCP ツールを使って Bring! ショッピングリストを操作できるようにします。

このサーバーは、Bring! API にアクセスするために bring-shopping npm パッケージを統合し、MCP に準拠したインターフェースを提供するために MCP TypeScript SDK v2 のサーバーパッケージを使用します。

免責事項：
これは個人プロジェクトです。私は Bring! Labs AG とは一切関係ありません。
このプロジェクトでは非公式の Bring! APIを使用しており、予告なく変更されたり、利用できなくなったりする可能性があります。
その場合、MCP サーバーが事前の通知なく動作しなくなる可能性があります。

---

🧩 Claude Desktop の推奨設定

npx を使って Claude Desktop でこのサーバーを使用するには、以下を claude_desktop_config.json ファイルに追加してください。

{
  "mcpServers": {
    "bring-mcp": {
      "command": "npx",
      "args": ["-y", "bring-mcp@latest"],
      "env": {
        "BRING_EMAIL": "[email protected]",
        "BRING_PASSWORD": "YOUR_BRING_PASSWORD_HERE"
      }
    }
  }
}

これは、最も推奨される汎用性の高い設定です。ローカルにインストールしなくても、npm で公開されている最新バージョンを常に使用できます。

---

💬 OpenAI Secure MCP Tunnel 経由で ChatGPT と使用する

OpenAI Secure MCP Tunnel を使うと、この STDIO サーバーを公開エンドポイント経由で公開することなく、ChatGPT からアクセスできます。トンネルクライアント自体はダウンロード可能なバイナリとして提供されますが、bring-mcp はローカルにチェックアウトしたりインストールしたりせずに、引き続き npx から起動できます。

前提条件

• Node.js 22 以降（npm／npx を含む）
• ChatGPT の開発者モードへのアクセス権
• 該当する OpenAI Platform 組織での Tunnels Read + Use 権限
• OpenAI Platform のトンネル設定で取得したトンネル ID とランタイム API キー
• トンネル設定のダウンロードリンクから入手できる tunnel-client バイナリ

トンネルを作成する際は、Bring を使用する ChatGPT ワークスペースに関連付けてください。そうしないと、ChatGPT の接続を作成するときに表示されません。

トンネルを設定して実行する

tunnel-client を実行するシェルで、トンネル API キーと Bring! の認証情報をエクスポートします。

export CONTROL_PLANE_API_KEY="sk-..."
export BRING_EMAIL="[email protected]"
export BRING_PASSWORD="YOUR_BRING_PASSWORD_HERE"

npx から公開済みの最新の bring-mcp パッケージを起動するトンネルプロファイルを作成します。

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile bring-mcp \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp-command "npx -y bring-mcp@latest"

設定を検証してから、トンネルを起動します。

tunnel-client doctor --profile bring-mcp --explain
tunnel-client run --profile bring-mcp

連携機能を使用している間は、このプロセスを実行したままにしてください。上記の環境変数は、npx から起動された MCP サーバーに引き継がれます。

ChatGPT でトンネルに接続する

1. ChatGPT で、設定 → セキュリティとログインを開き、開発者モードを有効にします。
2. ChatGPT Plugins を開き、プラスボタンを選択して開発者モードのアプリを作成します。
3. 名前と説明を入力し、接続でトンネルを選択して、上で作成したトンネルを選択します（または tunnel_id を入力します）。
4. 接続を作成し、検出された 16 個の Bring! ツールを確認します。
5. 新しいチャットを開始し、ツールメニューから Bring 接続を有効にして、「Bring のショッピングリストを表示して」のようなリクエストを試します。

ChatGPT がサーバーを検出できない場合は、tunnel-client run が引き続き実行中であることを確認し、doctor コマンドを再実行して、トンネルが正しい ChatGPT ワークスペースに関連付けられていることを確認してください。Secure MCP Tunnel はプライベート接続と開発者モードでのテストを目的としています。公開 ChatGPT プラグインを公開するには、安定した公開 HTTPS MCP エンドポイントが必要です。

---

🚀 機能

• 自動認証：手動ログインは不要です。最初の API 呼び出し時に自動で認証されます
• Bring! API の機能を MCP ツールとして提供します：
  • 🧾 買い物リストを読み込む
  • 🛒 アイテムを取得・変更する（追加、削除、移動）
  • 📦 一括操作（複数のアイテムを保存、複数のアイテムを削除）
  • 🖼 アイテム画像を保存・削除する
  • 👥 リストのユーザーを管理する
  • 🎯 デフォルトの買い物リストの UUID を取得する
  • 🌐 翻訳とカタログを読み込む
  • 📨 保留中の招待を取得する
• STDIO 経由で通信します（Claude Desktop または MCP Inspector で使用）
• MCP プロトコルリビジョン 2026-07-28 をサポートしながら、従来の 2025 クライアントにも引き続き対応します
• ツールのタイトル、アノテーション、具体的な入出力スキーマ、機械可読な構造化結果を公開します
• ツールの失敗時には isError: true を設定し、クライアントが成功した呼び出しと区別できるようにします
• .env ファイルまたは注入された環境変数を使用した Bring! 認証情報に対応します

利用可能なツール

• loadLists：Bring! のすべての買い物リストを読み込みます
• getItems：特定の買い物リストからすべてのアイテムを取得します
• getItemsDetails：リスト内のアイテムの詳細を取得します
• saveItem：任意の詳細情報を指定して、買い物リストにアイテムを保存します
• saveItemBatch：1 回の操作で、買い物リストに複数のアイテムを保存します
• removeItem：特定の買い物リストからアイテムを削除します
• moveToRecentList：アイテムを最近使用したアイテムのリストに移動します
• deleteMultipleItemsFromList：名前を指定して、リストから複数のアイテムを削除します
• saveItemImage：Base64 エンコードされた画像データからアイテム画像を保存します（デコード後の最大サイズ：5 MiB）
• removeItemImage：アイテムから画像を削除します
• getAllUsersFromList：買い物リストに関連付けられたすべてのユーザーを取得します
• getUserSettings：認証済みユーザーの設定を取得します
• getDefaultList：デフォルトの買い物リストの UUID を取得します（ユーザーがリストを指定しない場合に使用します）
• loadTranslations：Bring! インターフェースの翻訳を読み込みます
• loadCatalog：Bring! のアイテムカタログを読み込みます
• getPendingInvitations：買い物リストへの参加に関する保留中の招待を取得します

---

⚙️ セットアップとインストール

1. リポジトリをクローンする（またはファイルを入手する）

2. プロジェクトディレクトリに移動する：

   cd path/to/bring-mcp
   

3. 依存関係をインストールする：

   npm install
   

4. .env ファイルを作成する（ENV を直接注入しない場合）：

   [email protected]
   BRING_PASSWORD=your_password
   

5. プロジェクトをビルドする：

   npm run build
   

6. スクリプトを実行可能にする（Unix では任意）：

   chmod +x build/src/index.js
   

---

🏃 サーバーの実行

次のコマンドで MCP サーバーを起動します：

node build/src/index.js

成功すると、MCP server for Bring! API v<version> is running on STDIO と表示されます（stderr）。

---

🧪 MCP Inspector でテストする

1. npm run build を実行済みであることを確認します。

2. 有効な認証情報を含む .env があることを確認します。

3. Inspector を実行します：

   npx @modelcontextprotocol/inspector node /ABS/PATH/bring-mcp/build/src/index.js
   

---

🧩 Claude Desktop との連携（ローカルでの手動セットアップ）

または、ローカルでビルドしてインストールしたバージョンを使用する場合：

{
  "mcpServers": {
    "mcp-bring": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/bring-mcp/build/src/index.js"],
      "env": {
        "BRING_EMAIL": "[email protected]",
        "BRING_PASSWORD": "YOUR_BRING_PASSWORD_HERE"
      }
    }
  }
}

---

🔧 開発

テスト

次のコマンドでテストを実行します：

npm run test

このコマンドは、カバレッジレポートを作成しながら、フォーマット、リンティング、Jest テストを実行します。

CI テストの場合：

npm run test:ci

ビルド

プロジェクトをビルドします：

npm run build

主な依存関係とツール

• @modelcontextprotocol/server：MCP SDK v2 のサーバーおよび STDIO プロトコルディスパッチャー
• @modelcontextprotocol/client：エンドツーエンドのプロトコル互換性テストに使用する、開発専用クライアント
• @modelcontextprotocol/inspector：MCP サーバーのテストとデバッグに、必要に応じて npx で実行します
• bring-shopping：Bring! API 用の Node.js ラッパー
• zod：スキーマの定義と検証に使用します
• dotenv：環境変数の管理に使用します

---

✅ 最後に

• 🔒 .env ファイルをコミットしないでください。
• ♻️ 既存のインストール環境向けに、MAIL と PW は非推奨のエイリアスとして引き続きサポートされています。
• 🧼 認証情報をバージョン管理に含めないでください。
• 🛠 MCP Inspector はデバッグに非常に役立ちます。
• 🔄 認証は自動的に処理されるため、手動でログインする必要はありません。
• 📦 複数のアイテムを扱う場合は、効率化のためにバッチ操作を使用してください。

MCP と Bring で、コーディングをお楽しみください！🎉