Migrating eCommerce product data to Hygraph using Claude Code and MCP

Migrating product data between eCommerce systems is rarely an exciting process.

Whether you’re moving from WooCommerce, Shopify, or a legacy platform, you’re often left with a massive JSON export file. The real challenge isn’t exporting the data, but rebuilding your content model in a new CMS and importing everything safely without breaking your frontend.

In this tutorial, we’ll explore a different approach. Instead of manually recreating models and copying product data field by field, we’ll use Claude Code connected to Hygraph’s MCP (Model Context Protocol) server to:

• Analyze an existing WooCommerce product export
• Automatically design and update our CMS schema
• Apply safe, atomic migrations
• Import product data programmatically
• Switch a Next.js storefront from local JSON to Hygraph

By the end, we’ll have a fully functional headless eCommerce backend generated and migrated with AI assistance.

#Getting started

To simulate a real migration scenario, let’s work with a Next.js project that consumes a WooCommerce product export file locally.

Here’s a simplified look at the structure of the JSON export:

{
  "export_info": {
    "platform": "WooCommerce",
    "version": "8.4.0",
    "total_products": 10
  },
  "products": [
    {
      "id": 1001,
      "name": "Apple MacBook Pro 14-inch (M3 Pro)",
      "slug": "apple-macbook-pro-14-m3-pro",
      "sku": "AAPL-MBP14-M3P-SG",
      "regular_price": "1999.00",
      "sale_price": "1849.00",
      "stock_status": "instock",
      "stock_quantity": 24,
      "categories": ["Laptops", "Apple"],
      "tags": ["macbook", "apple", "laptop"],
      "images": [
        {
          "src": "https://images.unsplash.com/..."
        }
      ]
    }
  ]
}

The Next.js app pulls all product data from the WooCommerce-style export file:

import productsData from "@/data/woocommerce-products-export.json";

export function getAllProducts() {
  return productsData.products;
}

From there, pages render products directly from the local JSON file, but the goal is to move the data into a CMS like Hygraph so it’s easy to manage products as a team, localize, and do many other things without touching code.

#Setting up Hygraph and connecting MCP to Claude Code

To follow along with this tutorial, you’ll need a Hygraph account. If you don’t already have one, read the Hygraph quickstart guide for step-by-step instructions on creating a project and getting familiar with the dashboard.

Once your account is ready, create a new Hygraph project.

Normally, the next step would be to manually define your schema. Since this is an eCommerce example, I initially created a basic Product model and added a few obvious fields like name, slug, description, price, currency, inStock, stockQuantity, and image fields.

At that point, everything looked fine. But instead of continuing to manually mirror the WooCommerce structure, I wanted to see how far MCP could take this.

So I prompted Claude to compare my WooCommerce JSON export with the current Hygraph schema and point out any gaps.

Using the Hygraph MCP connection, inspect my current project schema.List the models and fields that exist right now (especially Product).

Once that worked, I pointed Claude at the WooCommerce export and asked it to compare the JSON structure against my current schema and highlight what I was missing:

I have a WooCommerce product export JSON at: data/woocommerce-products-export.json

Compare the JSON structure (including products, categories, tags, pricing, stock, images) with my current Hygraph schema.

Tell me which fields from the JSON aren't represented in Hygraph yet, which fields are mismatched (types, naming, structure) and what schema changes you recommend to support this export cleanly.

Claude immediately spotted gaps in areas such as sale_price, proper category modeling, and tags. It also suggested that categories shouldn’t just be a string array forever; they should be a real model with a relationship.

I followed up with a prompt to generate and apply the schema changes.

Instead of manually designing the schema first, you can create a blank Hygraph project, connect to MCP, and let Claude analyze your exported JSON to suggest and implement the most appropriate model structure.

Connecting Hygraph MCP to Claude Code

To make use of the Hygraph MCP, you need to first generate a Permanent Auth Token (PAT) in the Hygraph dashboard.

Go to Project Settings > Access > Permanent Auth Tokens and click Generate MCP PAT as shown below:

You’ll use this token to authenticate Claude’s MCP connection.

Once you have your PAT, configure the Hygraph MCP server in Claude Code. The exact setup depends on your environment, but conceptually it looks like this:

claude mcp add hygraph https://mcp-YOUR_PROJECT_HOSTED_REGION.hygraph.com/YOUR_PROJECT_IDENTIFIER/YOUR_ENVIRONMENT_NAME/mcp \
  --transport http \
  --header "Authorization: Bearer YOUR_HYGRAPH_TOKEN"

To get your MCP endpoint URL (which includes both the environment name and the hosted region), open your Hygraph dashboard and navigate to Project Settings > Endpoints.

You can now run the command in your terminal. Once this is successful, you can verify using the /mcp command:

At this point, Claude has visibility into your CMS via the available MCP tools. For example, there are tools like get_project_info, which is called when you use a prompt like “Can you access my Hygraph project?”:

#Migrating the WooCommerce products into Hygraph using MCP

The real advantage of MCP is that you can converse with Claude (or any AI agent) and have it reason about your project before taking action.

For example, imagine you’ve only created a blank Hygraph project with no models. Instead of manually building your schema from scratch, you can simply tell Claude:

Using the Hygraph MCP connection:

1. Inspect my current project.
2. Analyze the WooCommerce export at data/woocommerce-products-export.json.
3. Suggest what models and fields my schema should include.
4. Explain your reasoning before making changes.

Claude will inspect your project, detect whether models exist (or if they’re incomplete), and analyze the WooCommerce JSON structure. It will identify products, categories, pricing structure, stock data, tags, and images, and then suggest a clean content model to represent that structure inside Hygraph.

Once your schema is in place, you may want to pause before pushing the actual products.

If you look closely at the WooCommerce export, you'll see that every product includes image URLs. However, Hygraph doesn’t treat images as simple strings. By default, images are stored as Assets, so files must be uploaded to the media library before they can be linked to entries.

So you can ask Claude:

In my WooCommerce export, product images are URLs. Hygraph uses Asset fields for images.

How should we handle image migration using MCP? Can MCP upload the images directly? What are the best options?

This is where having an AI assistant is powerful. Claude explained that while MCP can create entries and connect relations through GraphQL, uploading binary files requires a separate multipart upload process. That means MCP alone cannot directly upload image files into Hygraph’s Asset system.

At this point, there are trade-offs. You could:

• Write a small upload script to push images first and then connect them.
• Upload assets manually.
• Or, for the purpose of a clean migration demo, store image URLs as string fields instead of Asset relations.

For this tutorial, I chose the third option. That meant removing the existing images and primaryImage Asset relation fields and replacing them with simple string fields like imageUrl and imageUrls.

Here’s another subtle but important detail about the Hygraph MCP. It supports creating and updating schema elements, but it does not support deleting fields.

So, the MCP helped create the new string fields. I then proceed to manually delete the old Asset relation fields from the Hygraph dashboard.

Now we’re ready to migrate

With the schema aligned and the image strategy decided, we’re finally ready to migrate the content.

At this stage, Claude already understands the WooCommerce JSON structure, the updated Hygraph schema, how image URLs should be mapped, and how categories relate to products.

You can now simply tell the AI:

Go ahead and migrate the WooCommerce export at data/woocommerce-products-export.json into Hygraph.

Ensure all relationships are handled correctly and publish the entries once created.

The MCP then kicks in by moving the categories first, mapping things properly, and moving all the products as drafts first. Claude always asks for your approval before calling the MCP tools. You can grant automatic permissions for similar tasks to speed up execution.

This took 5 mins and 9 secs:

The data also gets published:

It also properly formats the Rich text fields:

#Updating the Next.js storefront to fetch from Hygraph

At this point, the data is no longer sitting in a local JSON file. It lives inside Hygraph as structured content.

The only thing left is to update the Next.js app to fetch products from Hygraph instead of importing them from woocommerce-products-export.json.

Instead of manually writing everything from scratch, Claude can help here as well with a prompt like this:

The WooCommerce data has now been migrated into Hygraph.

Help me update my Next.js data layer to:

1. Fetch products from Hygraph using GraphQL.
2. Replace getAllProducts and getProductBySlug.
3. Keep the existing Product type shape as close as possible.
4. Use environment variables for the Hygraph endpoint.

Because Claude Code understands the project's structure, it generated the necessary GraphQL query, created a small fetch helper, adjusted the existing data functions, and wired everything together.

Within five minutes, the storefront stopped reading from a local JSON file and began pulling live data from Hygraph. All you need to do manually is grab your Hygraph Performance Content API endpoint:

Then add it to your .env.local file. You’ll also need to make sure your project grants at least read permissions for the Content API.

Once that’s done, restart your development server.

Now, when you visit the homepage, product listing page, or individual product pages, everything is powered by Hygraph.

You can access both the starter code (JSON-based) and the completed version (Hygraph-powered) on GitHub.

#Wrapping up

We started with a WooCommerce export and a Next.js app powered by static JSON. Instead of manually rebuilding the schema and copying data into a CMS, we connected Claude Code to Hygraph using MCP and let it:

• Analyze the exported data
• Design the appropriate schema
• Apply safe schema migrations
• Handle relationships
• Push structured content into Hygraph
• Help refactor the frontend to use GraphQL

Along the way, we made conscious trade-offs, like storing image URLs as strings to keep the migration fully MCP-driven, and saw firsthand where the Hygraph MCP excels (create, update, migrate) and where it has limitations (deleting fields, uploading binary assets).

The result is a fully working headless eCommerce backend powered by Hygraph, with a frontend that didn’t need to be rewritten. And the entire process was conversational.

That’s the real shift here. MCP turns your AI assistant from a code generator into an infrastructure-aware collaborator.