makeup.land

makeup.land MCP サーバー

makeup.land の Model Context Protocol サーバーに関する公開メタデータとインテグレーター向けガイドです。

makeup.land は、イスラエルのプロ向け化粧品小売店です。当社の MCP サーバーを使うと、AI エージェント（Claude Desktop、Cursor、ChatGPT のブラウジング機能、LangGraph アプリ、カスタムインテグレーション）から、Model Context Protocol の標準 JSON-RPC インターフェースを通じて、カタログの閲覧、顧客情報の検索、カートの取得、ギフトカードの確認ができます。

MCP サーバーは、Streamable-HTTP エンドポイント（プロトコルバージョン 2025-06-18、ステートレス）として https://makeup.land/api/mcp でホストされています。カタログツールは匿名で利用できます。顧客データツールの利用には、[email protected] から発行されたベアラートークンが必要です。

このリポジトリは、インテグレーションの公開窓口です。サーバーは非公開のストアフロントのコードベースで稼働していますが、インテグレーターに必要な情報（ツール一覧、認証方式、接続例、エラー形式）はすべてここにあります。

できること

ツール	返される内容	認証
list_products	カタログの閲覧：言語をまたいだセマンティック検索（q）、ΔE 順の色合いマッチング（商品ごとに shade_match: {hex, delta_e} を返します）、ブランド／ヘブライ語の完全一致タグによる絞り込み、価格／人気度／ベイズ縮約評価による並べ替え	匿名
validate_gift_card	ギフトカードの残高	公開（ギフトカードコードによる制限あり）
list_brands	取り扱いブランドの全一覧 — Yossi Bitton's B Cosmic、da Vinci (Defet) のブラシ、INGLOT、NYX など多数	ベアラー
get_customer	顧客プロフィール、ℳ クレジットウォレット、M Club のティア	ベアラー
get_cart	顧客の最新のカートと、明細ごとおよび合計の特典予測	ベアラー＋電話番号
list_orders	顧客の最近の注文と 6 軸のステータス	ベアラー＋電話番号
list_payment_links	未払い注文に対する保留中の支払いリクエスト	ベアラー＋電話番号
get_customer_best_deals	タグと M Club のティアに基づく、パーソナライズされたお得情報の予測	ベアラー＋電話番号

クイックスタート

ターミナルから

# Anonymous catalog browse — find lipsticks similar to a target shade
curl -X POST https://makeup.land/api/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "list_products",
      "arguments": { "near_hex": "#C2185B", "q": "lipstick", "limit": 5 }
    }
  }'

# List all Yossi Bitton (B Cosmic) products — bearer required
curl -X POST https://makeup.land/api/mcp \
  -H 'Authorization: Bearer ml_<your-token>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list_products",
      "arguments": { "brand": "yossi-bitton", "limit": 20 }
    }
  }'

Claude Desktop から

mcp-remote ブリッジを使います（Claude Desktop は stdio 経由で MCP を読み取るため、HTTP エンドポイントに接続するにはこのブリッジを使います）。

{
  "mcpServers": {
    "makeup.land": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://makeup.land/api/mcp",
        "--header", "Authorization:Bearer ml_<your-token>"
      ]
    }
  }
}

匿名でカタログのみを利用する場合（ベアラーを省略）：

{
  "mcpServers": {
    "makeup.land": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://makeup.land/api/mcp"]
    }
  }
}

Cursor から

Cursor は ~/.cursor/mcp.json（またはワークスペースごとの .cursor/mcp.json）から読み取ります。設定形式は上記の Claude Desktop と同じです。

取り扱いブランド

カタログには約 150 のブランドが含まれています。主なブランドをいくつか紹介します。

• Yossi Bitton (B Cosmic) — スタイリストの Yossi Bitton によるイスラエルのプロ向けメイクアップラインです。makeup.land は公式オンラインストアです。
• da Vinci (Defet) — ドイツ製のプロ向け化粧筆 da Vinci のイスラエル正規代理店です。
• Yarin Shahaf — カタログ横断のパートナーです（yarin-shahaf.co.il/מייקאפלנד）。
• INGLOT、NYX、Bourjois、Maybelline、L'Oréal など、ほか 140 以上のブランドを取り扱っています。

list_brands を使うと、実行時にすべてのブランドを列挙できます。

ΔE による色合いマッチング

主力機能です。カタログ内のすべてのバリアントには、スウォッチの HEX カラーが設定されています。list_products ツールの near_hex 引数は、知覚的距離（CIE ΔE 2000）に基づいて順位付けするため、エージェントは「#C2185B に似た口紅を探して」と一度の呼び出しで回答できます。hue_family=warm|cool|neutral を組み合わせると、さらに絞り込めます。

返される各商品には、最も近いバリアントのスウォッチとその知覚的距離を示す shade_match: {hex, delta_e} フィールドがあります。そのため、40 色のパレットであれば、どのパレットが一致したかだけでなく、具体的にどの色合いが一致したか（およびどの程度近いか）もわかります。

これこそが、makeup.land の MCP サーバーをショッピングエージェントにとって唯一無二の便利な存在にしている機能です。MCP を通じて色合いマッチングを提供するイスラエルの化粧品小売店はほかになく、世界的に見ても、これを提供する小売店はごくわずかです。

クロスリンガルカタログ検索

カテゴリ検索では、tag の代わりに q（自然言語）を指定してください。q はクロスリンガルなセマンティック検索です。q="lipstick"、q="שפתון"、q="lápiz labial" のいずれも、ヘブライ語タグが付いた口紅を返します。表示される商品セットは、クエリの言語によって異なる場合があります（システムは言語の正規化ではなく、セマンティックな関連性に基づいて順位付けします）が、いずれも有効な口紅のページです。tag は、ヘブライ語で保存されたタグのみを対象とする文字列の完全一致フィルターです。英語のカテゴリ語は一致しません。

認証

モード	必要な場合	方法
匿名	list_products（カタログフィルターのみ）、validate_gift_card	何も必要ありません。呼び出すだけです
Bearer	すべての顧客データツール、list_brands	Authorization: Bearer ml_<hex>
Bearer + 電話番号	get_cart、list_orders、list_payment_links、get_customer_best_deals	Bearer は呼び出し元を認証します（パートナー連携）。電話番号（E.164）で顧客を選択します

Smithery の自動検出とは異なり、Bearer 認証は OAuth ではありません。トークンはメールで別途発行されます。トークンをリクエストするには、連携の用途を記載して [email protected] までご連絡ください。

Bearer + 電話番号が必要な理由

電話番号の識別子（?phone=+972...）で、どの顧客のリソースを返すかを指定します。Bearer は、誰が呼び出しているかを認証します。どちらか一方だけでは不十分です。Bearer だけでは顧客レコードを列挙できず、電話番号だけでは 401 Unauthorized が返されます。これは V1 REST API の仕様であり、MCP サーバーはこれに正確に準拠しています。

エラーエンベロープ

ツールのエラーは、V1 REST のエラーエンベロープから isError: true を含むテキストコンテンツとして伝播します。

{
  "content": [{
    "type": "text",
    "text": "{ \"error\": \"...\", \"error_code\": \"...\" }"
  }],
  "isError": true
}

安定した error_code の値は、OpenAPI 仕様の components.schemas.Error に記載されています。一般的なコードは次のとおりです。

• unauthorized — Bearer がない、または無効です
• scope_mismatch — トークンのスコープがツールに適合していません
• read_only_token — 読み取り専用トークンで書き込みが試行されました
• customer_not_found — 電話番号に一致する顧客がいません
• endpoint_not_found — V1 パスに誤記があるか、削除されています
• insufficient_stock — バリエーションが在庫切れです（書き込みツールの提供開始後に該当します）
• insufficient_credits — ウォレット残高ではクレジット払いの購入を賄えません

v1 の制限事項

• 読み取り専用です。 カートへの書き込み、ギフトカードの引き換え、顧客登録はできません。v2 で対応します。
• ステートレスです。 リクエストごとに新しい MCP セッションが初期化されます。
• 同期処理です。 tools/call は V1 内部フェッチが完了するまで待機します。ほとんどの呼び出しは 500ms 未満で返りますが、セマンティック検索には最大 2 秒かかる場合があります。
• 部分的な結果を返す SSE ストリーミングには対応していません。

ディスカバリーの参照先

参照先	URL
MCP ディスカバリーマニフェスト	https://makeup.land/.well-known/mcp.json
A2A エージェントカード	https://makeup.land/.well-known/agent-card.json
OpenAPI 3.1 仕様	https://makeup.land/openapi.json
認証スキルマニフェスト	https://makeup.land/auth.md
詳細ハンドブック	https://makeup.land/llms-full.txt
OAuth リソースメタデータ	https://makeup.land/.well-known/oauth-protected-resource
OAuth サーバーメタデータ	https://makeup.land/.well-known/oauth-authorization-server

掲載先

• Smithery
• 公式 MCP Registry（land.makeup/v1 として掲載）
• makeup.land インテグレーターガイド

お問い合わせ

• トークンのリクエスト： [email protected]
• バグ報告と機能リクエスト： このリポジトリで issue を作成してください
• 一般的なお問い合わせ： [email protected]

ライセンス

このリポジトリのメタデータとドキュメントは、MCP カタログアグリゲーターが再配布できるよう、MIT ライセンスで公開されています。

基盤となる MCP サーバー、makeup.land のストアフロント、および商品カタログは引き続きプロプライエタリです。詳細は makeup.land/terms-of-service をご覧ください。