yampi-mcp

Claude から Yampi ストアを操作できる MCP サーバーです。注文の検索、商品の作成、在庫の調整、クーポンやオファーの作成ができます。

各マーチャントは Cloudflare 上に自分のコピーをホストします。これはサービスではありません。あなたの認証情報を保持するのはあなただけです。 非公式であり、Yampi とは提携していません。

仕組み

Yampi の認証情報はストアではなくユーザーに属します。1つのログインで4つのストアを運営している場合、4つすべてが表示されます。一度接続すれば、各コマンドでストアを選択できます。

Related MCP server: MCP Shopify

セットアップ

Cloudflare アカウント（無料プランで十分です）と Node のインストールが必要です。

git clone https://github.com/Eduardo-Orsi/yampi-mcp && cd yampi-mcp
npm install
cp wrangler.example.jsonc wrangler.jsonc
npx wrangler kv namespace create OAUTH_KV   # paste the returned id into wrangler.jsonc
npx wrangler deploy

Claude クライアント（claude.ai、Desktop、または Code）で、https://yampi-mcp.<your-subdomain>.workers.dev/mcp を指すカスタムコネクタを追加します。

接続時に、User-Token と User-Secret-Key の入力を求める画面が表示されます。これらは Yampi ダッシュボードの Perfil › Credenciais de API（プロフィール › API 認証情報）にあります。これだけです。作成するパスワードはありません。

使い方

接続後は、普通の会話で操作できます：

「6月1日から15日の間にストアXで支払い済みの注文は何件ですか？」 「Black T-Shirt という商品、ブランド Acme、SKU TS-BLACK-M、R$ 79.90、在庫20個で作成して。」 「SKU TS-BLACK-M の価格が間違っています。R$ 89.90 に変更して、在庫を5に減らしてください。」 「今週放棄されたカートはどれですか？合計はいくらですか？」 「月末まで有効な15%オフのクーポンを作成して。最低購入額 R$ 100、使用回数50回で。」

アカウントに複数のストアがある場合は、どれかを指定してください。ツールは明示的な指定を必須としているため、誤ったストアに書き込まれることはありません。

機能

⚠️ ライブ API で検証されていません。 他の13個は実際のストアに対してエンドツーエンドで実行済みです（商品の作成、価格の変更、在庫の書き込み、クーポンの発行）。フィールド名はその過程で修正されました。この2つは既存の注文が必要ですが、テストストアには注文がありませんでした。エンドポイントは正しいです。リクエストボディはドキュメントに基づいていますが、他の5つの書き込み操作のすべてで、ドキュメントには必須フィールドが少なくとも1つ欠けていることが判明しました。最初の呼び出しで 422 が返ることを想定してください。メッセージに欠落フィールドが示されます。

意図的に行わないこと

注文のキャンセル、返金、決済ゲートウェイの切り替えは行いません。 環境変数の背後にある機能ではありません。コード自体が存在しません。これらは API で取り消し不能な操作であり、Claude Desktop も claude.ai も elicitation をサポートしていないため、サーバーが本当の意味で確認を求める方法がありません。誰かが注意を払っていることに依存しない唯一の保証は、機能が存在しないことです。

この禁止は2箇所で強制されており、両方ともテストでカバーされています。ステータスエイリアス（tools/write.ts）と、すべてのリクエストが通過する継ぎ目（yampi.ts）です。根拠は docs/adr/0002 にあります。

注文追跡も対象外です。Yampi はそのルートを1時間あたり3リクエストに制限しており、実際にはツールとして使い物になりません。2回呼び出すとエージェントは20分間動けなくなります。

あなたの認証情報

• OAuth グラントのプロパティに暗号化（AES-GCM）されて保存され、あなたの KV 内にあります。

• 認証情報を暗号化するキーは、アクセストークンから導出されたキーでラップされ、KV にはトークンのハッシュのみが保持されます。KV が漏洩しただけでは認証情報は開示されません。

• Claude が受け取ることはありません。不透明なトークンのみが表示されます。

• 失効させるにはグラントを削除します。他の接続は引き続き機能します。

/authorize は公開されており認証情報を検証するため、技術的には盗まれたキーをテストするためのオラクルになります。そのため、IP あたり毎分5回の試行制限があります。

インスタンスを特定のストアに制限するには：

npx wrangler secret put ALLOWED_STORES   # e.g. my-store,other-store

API 制限

Yampi のルートごとの毎分制限：商品と SKU は 30 req/min、注文読み取りは 120、書き込みは 30、一般は 60。サーバーは include= を使用して N+1 ではなく単一の呼び出しでリレーションを取得し、すべてのレスポンスから X-RateLimit-Remaining を読み取り、クォータが尽きかけているときにモデルに警告します。429 で気付くのではなく。

問題が発生したとき

すべてで 403（読み取りも含む）。 Yampi ダッシュボードでストアが active: false になっています。非アクティブなストアはすべてのルートを拒否します。再アクティブ化してから、コネクタを再接続してください。

書き込みで 422。 メッセージは Yampi が拒否した正確なフィールドを示します。サーバーは errors オブジェクト全体を転送します。Claude は通常、次の試行で自分自身を修正します。

「認証情報のないグラント」。 グラントがプロパティを失いました。コネクタを削除して再度追加してください。

認証情報の切り替え。 再接続するだけです。新しいグラントが古いものを置き換えます。再接続せずにアクセスを遮断するには、KV 名前空間を削除します。

ストアがリストにない。 非アクティブであるか、認証情報がそのストアに到達していません。describe_store を実行して、サーバーが何を見ているかを確認してください。

Yampi API の癖

ライブ API でのテストで発見されました。すべて時間を何時間も浪費させる可能性があり、ドキュメントからは明らかではありません：

• フィルタには配列構文が必要です。 ?status_id=4 は黙って無視され、データセット全体を返します。?status_id[]=4 はフィルタリングします。active[] も同様です。フィルタリングしないフィルタはフィルタなしより悪いです。エージェントは7月の分を見たと思って55,000件の注文を要約します。

• 日付は独自形式です：?date=created_at:2026-06-01|2026-06-30。それ以外は 500 を返すか無視されます。

• filters[...] はフィルタリングしません。 レスポンスを scroll_id ページネーションに切り替えるだけです。

• /auth/me は GET ではなく POST であり、認証情報上のすべてのストアを返します。認証情報はストアではなくユーザーに属するためです。

• 注文の include は閉じた列挙型です：items、customer、marketplace、status、statuses、shipping_address、promocode、transactions、comments、files、discounts、seller、labels。payments はありません。

• GET レスポンスは Yampi 側で30分間キャッシュされます。 エージェントのコンテキストではこれは嘘をつきます。商品を作成して読み戻すよう依頼すると、以前の状態が返ります。このサーバーはすべての読み取りで ?skipCache=true を送信します。

• 在庫は SKU フィールドではありません。 SKU の quantity は常に null です。ライブストアの実際の SKU でも同様です。在庫は /logistics/stocks（在庫ロケーション）にあり、/catalog/skus/{id}/stocks で SKU に結合されます。また、stock_id は /logistics/warehouses の ID ではありません。これはまったく別のリソースです。

• クーポンの discount_type は p または v のみを受け付けます。 percentage/fixed ではありません。

• クーポンの日付は Y-m-d H:i:s が必要です。 日付のみでは 422 が返ります。

• PUT /catalog/skus/{id} は部分更新でも product_id と price_cost が必要です。

• 商品の作成には simple、brand_id、skus.*.blocked_sale が必要です。 どれも明白ではありません。

• active: false のストアはすべてで 403 を返します（読み取りも含む）。 このサーバーは接続時にこれらのストアをフィルタリングするため、モデルに失敗するしかないオプションが提示されることはありません。

• 422 レスポンスには失敗した正確なフィールドを示す errors オブジェクトが含まれます。 ステータスコードのみを表示するのではなく、モデルに転送する価値があります。それによってモデルは自分自身を修正できるからです。

開発

npm test              # 32 unit tests, no network
npm run typecheck
npm run dev           # wrangler dev

自分のストアでのテスト

ユニットスイートは偽の fetch を使用してサーバーのロジックを証明します。Yampi がエンドポイント、フィールド名、フィルタ構文を変更したことに気付くことはできません。そして、このプロジェクトの構築中にそれは繰り返し発生しました。そのもう半分は、ライブ API にアクセスする統合スイートでカバーされています。読み取り専用で、何も作成も変更もありません：

cp .env.example .env    # fill in the alias and credentials of YOUR store
npm run test:integration

ストアの検出が機能すること、ステータスエイリアスが存在すること、ステータスによるフィルタリングが実際にフィルタリングすること、日付形式が受け入れられること、include がリレーションを展開すること、クォータヘッダーが届くことをチェックします。1つでも失敗したら、API が変更されたということです。サーバーは壊れる前に嘘をつき始めます。

アーキテクチャには1つのルールがあります：ツールは HTTP を話しません。 すべては src/yampi.ts を通過します。これにより、「禁止ルートに到達しない」という約束が監査可能になります。全体の表面積が1つのファイルに収まるからです。

プロジェクトの語彙は CONTEXT.md にあります。決定事項は docs/adr/ にあります。

既知の制限

• 注文追跡なし（Yampi の 3 req/h の制限で使い物にならない）。

• バナー、送料無料ルール、段階的割引、コンボなし。

• advance_order_status と add_order_comment はライブ API で実行されたことがない。

• 在庫はストアの最初に登録された在庫ロケーションに書き込まれます。複数のロケーションを使用する人は、src/tools/write.ts の defaultStockId() を調整する必要があります。

貢献

プルリクエストを歓迎します。フォークして main に対して PR を開いてください。CI が型チェックとユニットテストを実行します。バグ修正より大きいものは、まずイシューを開いてください。

パッチの品質に関係なくマージされないものが1つあります：注文のキャンセル、購入の返金、決済ゲートウェイの切り替えを行うもの。間接的なルートも含みます。その不在こそがこのプロジェクトの要点です — 根拠は ADR 0002 にあります。

詳細は CONTRIBUTING.md にあります。セキュリティの問題を見つけましたか？公開イシューを開かないでください — SECURITY.md を参照してください。

ライセンス

MIT — LICENSE を参照してください。

assets/ にある Yampi ロゴは Yampi の商標であり、このサーバーがどのプラットフォームと通信するかを識別するためにのみ使用されています。これは MIT ライセンスの対象外であり、このプロジェクトは Yampi とは提携しておらず、Yampi による承認も受けていません。