Shopify Storefront MCP Server

Shopify Storefront MCP サーバー

このサーバーは、MCP 経由で Shopify Storefront API にアクセスできるようにし、AI アシスタントが Shopify ストアのデータを照会して操作できるようにします。

機能

• 商品、コレクション、在庫データへのアクセス
• カートの作成と管理
• GraphQL クエリとミューテーションへの対応
• トークンの自動処理と検証
• MCP 対応 AI アシスタントとの簡単な連携

セットアップ手順

1. このリポジトリをクローンします
2. 依存関係をインストールします：pip install -r requirements.txt
3. .env.example を .env にコピーし、環境変数を設定します
4. Shopify Admin で Storefront API トークンを生成します（下記を参照）
5. サーバーを実行します：python -m shopify_storefront_mcp_server

環境変数

テンプレートとして提供されている .env.example を使用して、.env ファイルを作成します。

# Required
SHOPIFY_STOREFRONT_ACCESS_TOKEN=your_storefront_token
SHOPIFY_STORE_NAME=your-store-name

# Optional
SHOPIFY_API_VERSION=2025-04
SHOPIFY_BUYER_IP=127.0.0.1

Storefront API トークンの生成

1. Shopify Admin にログインします
2. アプリと販売チャネル > アプリを開発 > アプリを作成 に移動します
3. アプリに名前を付けます（例：「MCP Storefront」）
4. API 認証情報 > Storefront API のスコープを設定 に移動します
5. 必要なスコープを選択します：
   • unauthenticated_read_product_listings
   • unauthenticated_read_product_inventory
   • unauthenticated_read_product_pricing
   • unauthenticated_write_checkouts
   • unauthenticated_read_content
6. 保存し、生成された Storefront API アクセストークンをコピーします
7. トークンを SHOPIFY_STOREFRONT_ACCESS_TOKEN として .env ファイルに追加します

使用例

MCP サーバーを実行する場合：

python -m shopify_storefront_mcp_server

サーバーは次の MCP ツールを公開します：

• shopify_discover：URL が Shopify ストアフロントに属するかを検出し、認証トークンを見つけます
• shopify_storefront_graphql：Storefront API に対して GraphQL クエリを実行します
• customer_data：すべての顧客データ操作（作成、読み取り、更新、削除）を行う統合ツールです

顧客リソース

このサーバーは、顧客情報用の MCP リソースも提供します：

• customer://name：顧客の氏名
• customer://email：顧客のメールアドレス
• customer://phone：顧客の電話番号
• customer://shipping_address：顧客の配送先住所（address1、address2、city、state、postal_code、country を含む）
• customer://billing_address：顧客の請求先住所（address1、address2、city、state、postal_code、country を含む）
• customer://profile：顧客の完全なプロフィール

顧客データは user_data/customer.json に保存され、customer_data ツールを使用して管理する必要があります。

顧客データの管理

サーバーは、すべての顧客情報を管理するための統合 customer_data ツールを提供します。このツールは、作成、読み取り、更新、削除の操作を単一のインターフェースにまとめています。

例：

# Get all customer data
customer_data(operation="get")

# Get a specific field
customer_data(operation="get", field="name")
customer_data(operation="get", field="shipping_address")

# Update a specific field
customer_data(operation="update", field="name", value="Jane Doe")
customer_data(
    operation="update",
    shipping_address={
        "address1": "123 Main St",
        "address2": "Apt 4B",
        "city": "New York",
        "state": "NY",
        "postal_code": "10001",
        "country": "US"
    }
)

# Add custom fields
customer_data(
    operation="update",
    custom_fields={
        "preferences": {
            "theme": "dark",
            "notifications": "email",
            "language": "en-US"
        },
        "loyalty_tier": "gold",
        "last_purchase_date": "2023-06-15"
    }
)

# Get a custom field
customer_data(operation="get", field="preferences")
customer_data(operation="get", field="loyalty_tier")

# Update single custom field
customer_data(operation="update", field="loyalty_tier", value="platinum")

# Delete a specific field
customer_data(operation="delete", field="phone")
customer_data(operation="delete", field="preferences")

# Delete all customer data
customer_data(operation="delete")

この統合ツールにより、標準的な顧客情報と、パーソナライズに役立つカスタムフィールドの両方を含む、すべての顧客データ操作に一貫したインターフェースを提供できるため、AI アシスタントとの連携が簡単になります。

データのプライバシーと保存

顧客データは user_data/customer.json に保存されます。このファイルには個人情報が含まれるため、バージョン管理にコミットしないでください。リポジトリには次のものが含まれています：

• user_data/customer.json.example：ダミーデータを使って想定される構造を示すテンプレートファイル
• 実際の顧客データを誤ってコミットしないようにする .gitignore のエントリー

このサーバーをデプロイすると、customer_data ツールが初めて使用されたときに user_data/customer.json ファイルが自動的に作成されます。開始するには、サンプルファイルをコピーして名前を変更することもできます：

cp user_data/customer.json.example user_data/customer.json

顧客ファイルに保存されたすべてのデータは、サーバーを再起動しても保持されます。このファイルは、標準的な顧客フィールド（名前、メールアドレス、住所）と、AI によるパーソナライズ用の任意のカスタムフィールドの両方に対応しています。

顧客データを使ったチェックアウトの作成

customer_data と shopify_storefront_graphql のツールを組み合わせることで、顧客情報を含む Shopify のチェックアウトを簡単に作成できます。

ワークフローの例：

# Step 1: Get customer data
customer_profile = customer_data(operation="get")

# Step 2: Create a cart with GraphQL
cart_mutation = """
mutation createCart($lines: [CartLineInput!]!) {
  cartCreate(input: {lines: $lines}) {
    cart {
      id
      checkoutUrl
    }
    userErrors {
      field
      message
    }
  }
}
"""

cart_variables = {
  "lines": [
    {
      "merchandiseId": "gid://shopify/ProductVariant/12345678901234",
      "quantity": 1
    }
  ]
}

cart_result = shopify_storefront_graphql(
  mode="execute",
  host="your-store.myshopify.com",
  token="your_storefront_token",
  query=cart_mutation,
  variables=cart_variables
)

# Step 3: Apply customer attributes to the cart
cart_id = # extract from cart_result
customer_info = json.loads(customer_profile)

attributes_mutation = """
mutation updateCartAttributes($cartId: ID!, $attributes: [AttributeInput!]!) {
  cartAttributesUpdate(cartId: $cartId, attributes: $attributes) {
    cart {
      id
      checkoutUrl
    }
    userErrors {
      field
      message
    }
  }
}
"""

attributes_variables = {
  "cartId": cart_id,
  "attributes": [
    {
      "key": "email",
      "value": customer_info["email"]
    },
    {
      "key": "deliveryAddress",
      "value": json.dumps(customer_info["shipping_address"])
    }
  ]
}

shopify_storefront_graphql(
  mode="execute",
  host="your-store.myshopify.com",
  token="your_storefront_token",
  query=attributes_mutation,
  variables=attributes_variables
)

この方法では、保存済みの顧客情報を活用しながら、チェックアウトプロセスを完全に制御できます。

トラブルシューティング

認証エラーが発生した場合：

1. トークンの形式を確認します：Storefront API トークンは shpsa_（新しい形式）または shpat_（古い形式）で始まる必要があります
2. ストア名を確認します：SHOPIFY_STORE_NAME が正しいことを確認します（.myshopify.com は付けません）
3. API バージョンを確認します：API バージョンがサポートされていることを確認します
4. トークンをテストします：cURL を使ってトークンを直接テストします：

   curl -X POST \
     https://your-store.myshopify.com/api/2025-04/graphql.json \
     -H "Content-Type: application/json" \
     -H "X-Shopify-Storefront-Access-Token: your_token" \
     -d '{"query": "query { shop { name } }"}'
   

5. トークンを再生成します：問題が解決しない場合は、適切なスコープを設定して新しいトークンを作成します

セキュリティに関する考慮事項

• .env ファイルや API トークンを含むファイルをコミットしないでください
• すべての機密情報に環境変数を使用してください
• Shopify Admin で IP 制限を設定することを検討してください
• Storefront API トークンに付与された権限を確認してください