# Shopify SEO Metadata Checker & Audit Tool (`mabelsays/shopify-seo-metadata-checker`) Actor

Audit Shopify product, collection, and content-page SEO metadata. Find missing titles, duplicate meta descriptions, H1 errors, canonical issues, and Open Graph problems. Get a custom SEO score for each page and export results as CSV or JSON.

- **URL**: https://apify.com/mabelsays/shopify-seo-metadata-checker.md
- **Developed by:** [Mabel Says](https://apify.com/mabelsays) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 shopify seo audited pages

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Mabel Says — Shopify SEO Metadata Checker

**Find out what's wrong with your Shopify SEO, what it means, and exactly how to fix it.**

**Works with Claude and AI assistants:** Run Shopify SEO audits through Apify MCP and ask your AI assistant to explain what needs fixing.

Built for everyday Shopify store owners—not just SEO specialists. Paste your store URL, run the audit, and get plain-English explanations with Shopify Admin (or theme) fix steps for each problem.

This Actor runs on the [Apify platform](https://apify.com): schedule audits, export CSV/JSON, call it from the API, use it from Claude (and other MCP clients), or plug it into Zapier, Make, or n8n.

### Why store owners use this

Search listings and social previews start with on-page details: titles, descriptions, headings, and preferred URLs. When those are missing, duplicated, or unclear, shoppers get a weaker first impression.

Mabel Says checks the pages on your public Shopify storefront and tells you:

1. **What’s wrong** — in everyday language
2. **Why it matters** — honest impact, without fake “rank #1” promises
3. **How to fix it** — clear steps
4. **Where to fix it** — Shopify Admin search engine listing, theme code, or a developer task

You do **not** need to know HTML, canonical tags, or SEO jargon to use the report.

### What the tool checks

On each audited page:

| Check | Store-owner meaning |
| --- | --- |
| **Page title** | The clickable name search engines may show |
| **Meta description** | The short summary under that title |
| **Main heading (H1)** | The big on-page heading customers see |
| **Canonical URL** | The “preferred” address for this page |
| **Open Graph tags** | How the link can look when shared on social apps |
| **Robots / noindex** | Whether the page asks search engines not to list it |
| **Duplicate titles & descriptions** | Same wording reused on more than one page **in this audit** |

### What you receive after a run

Each dataset row is one unique page, including:

- The metadata we found (title, description, H1, canonical, Open Graph)
- A **custom heuristic score (0–100)** — labeled `scoreType: custom_heuristic_v1`\
  **This is not an official Google score** and does not predict rankings
- A simple `issues` list (compatible with older exports)
- **`issueDetails`** — structured plain-English guidance for every issue, sorted **High → Medium → Low**
- CSV-friendly “top issue” fields so spreadsheets stay readable

#### How to read priorities

| Priority | Meaning |
| --- | --- |
| **High** | Important problems that deserve prompt review (for example missing title or meta description, broken canonical, noindex) |
| **Medium** | Worth fixing soon (for example duplicates within this audit, failed page loads) |
| **Low** | Optional polish (title/description length guidance, missing Open Graph tags) |

**Errors** are genuine detected gaps. **Recommendations** (length guidance, Open Graph) are best-practice tips—not confirmed Google ranking errors.

#### Example: missing meta description

**Before (technical-style issue string):**\
`Missing meta description`

**After (plain English in `issueDetails` / top-issue fields):**

- **Issue:** Missing meta description
- **What this means:** Your page does not have its own description for search engines to consider showing under the title in search results.
- **Why it matters:** A useful description can help shoppers understand what the page offers before they click.
- **How to fix it:** Write a unique description that explains what someone will find on this page.
- **Where to fix it:** Shopify Admin → Products → open the product → Search engine listing → Edit

Theme-level items (H1, canonical) point to **Online Store → Themes → Edit code** (or a developer)—not the product editor. See [Shopify theme SEO metadata](https://shopify.dev/docs/storefronts/themes/seo/metadata).

### Who benefits

- **Shopify store owners** who want a clear to-do list without SEO jargon
- **Marketing teams** who need a repeatable metadata checklist
- **Agencies & freelancers** who want scored JSON/CSV for client reports
- **Developers** who still get full technical fields and issue codes
- **Claude / AI assistant users** who want to run audits through Apify MCP and get plain-English fix guidance in chat

### How to run (3 steps)

1. Paste your Shopify store homepage into **Start URLs** (for example `https://your-store.com`).
2. Set **Max pages to audit** (try 25–50 first). Keep concurrency at `1` and delay at `2` unless you know the store can handle more.
3. Click **Start**, open the **Dataset** tab, and use the **Store owner summary** view (or export CSV/JSON).

Optional: set **Locale filter** (for example `en`) to focus on one language/market. Multilingual stores are supported; leave the filter empty to audit all locales discovered in the crawl.

### Run Shopify SEO Audits from Claude

You can use Shopify SEO Metadata Checker directly from Claude Chat or Claude Desktop through Apify's MCP integration.

**How to connect:**

1. Open Claude → Settings → Connectors.
2. Select Add → Add custom connector.
3. Name the connector `Apify`.
4. Enter `https://mcp.apify.com` as the remote MCP server URL.
5. Authorize your Apify account.
6. Ask Claude to run `mabelsays/shopify-seo-metadata-checker`.

**Example prompt:**

> Use the Mabel Says Shopify SEO Metadata Checker to audit 100 pages of myshop.com. Explain the most important SEO issues in simple English, show me which pages need attention, and tell me how to fix each problem in Shopify.

Customers must connect Apify and authorize Actor runs. Applicable Apify Actor charges still apply.

Full setup guide: [Apify Claude Desktop integration](https://docs.apify.com/integrations/claude-desktop).

### Example input

```json
{
    "startUrls": [{ "url": "https://mabelloveco.com" }],
    "maxRequestsPerCrawl": 50,
    "maxConcurrency": 1,
    "sameDomainDelaySecs": 2,
    "localeFilter": "",
    "checkProducts": true,
    "checkCollections": true,
    "checkPages": true,
    "proxyConfiguration": { "useApifyProxy": false }
}
```

### Example output (abbreviated)

```json
{
    "url": "https://mabelloveco.com/products/example",
    "pageType": "product",
    "title": null,
    "metaDescription": null,
    "issues": ["Missing title tag", "Missing meta description"],
    "issueDetails": [
        {
            "code": "missing_title",
            "issue": "Missing page title",
            "whatThisMeans": "This page has no title for browsers and search results to use.",
            "whyItMatters": "Without a title, shoppers and search engines get little context about the page. This is a real on-page gap, not a ranking guarantee.",
            "howToFix": "Add a clear, unique page title that names the product, collection, or page. Avoid leaving the search engine listing blank.",
            "whereToFix": "Shopify Admin → Products → open the product → Search engine listing → Edit",
            "priority": "High",
            "kind": "error"
        }
    ],
    "topPriority": "High",
    "topIssue": "Missing page title",
    "topIssueHowToFix": "Add a clear, unique page title that names the product, collection, or page. Avoid leaving the search engine listing blank.",
    "topIssueWhereToFix": "Shopify Admin → Products → open the product → Search engine listing → Edit",
    "score": 55,
    "scoreType": "custom_heuristic_v1",
    "scoreNote": "Custom heuristic score (0–100). Not an official Google ranking score. Severe on-page gaps weigh more than length or Open Graph recommendations.",
    "fetchStatus": "ok"
}
```

Failed fetches still appear with `fetchStatus: "failed"` so you can see what could not be audited. They are **not** billed.

### Fixing common issues in Shopify

| Problem | Typical fix location |
| --- | --- |
| Missing / weak title or meta description | Admin → product, collection, or page → **Search engine listing** ([storefront SEO metafields](https://shopify.dev/docs/apps/build/marketing/optimize-storefront-seo)) |
| Homepage title / description | Admin → **Online Store → Preferences** (or theme overrides) |
| Missing or multiple H1, bad canonical | Theme (`layout/theme.liquid` / `canonical_url`) — often needs a developer ([theme SEO metadata](https://shopify.dev/docs/storefronts/themes/seo/metadata)) |
| Missing Open Graph image on a product | Product **Media** (featured image), then theme OG markup if still missing |
| Duplicate title/description | Rewrite the listing for that product/page; duplicates are only detected **among pages in this run** |

This Actor **never edits your store**. It only reads public HTML.

### Pricing

| What you pay for | Event name | Price (FREE tier) |
| --- | --- | --- |
| Each **successfully audited** page | `audited-page` | **$0.004** |
| Actor start | `apify-actor-start` | $0.00005 (one event per GB of memory, minimum one) |

- You pay only for **successful** SEO audits (`fetchStatus: "ok"`). Failed fetches and duplicate skips are **not** charged.
- There is **no separate platform-usage charge** on top of these events (standard pay-per-event).
- Example: **100 successful pages** ≈ **$0.40** in `audited-page` charges, plus the small Actor-start fee.

### Input fields

| Field | Default | Description |
| --- | --- | --- |
| Start URLs | `https://mabelloveco.com` | Storefront homepage (or other seed URLs) |
| Max pages to audit | `50` | Cap on pages fetched this run |
| Max concurrency | `1` | Parallel fetches (keep low to avoid 429s) |
| Delay between requests | `2` | Seconds between same-domain requests |
| Locale filter | empty | e.g. `en` / `en-us`, or empty for all locales |
| Include product / collection / content pages | `true` | Toggle URL types |
| Proxy | off | Optional Apify Proxy |

### Scoring (custom heuristic — not Google)

| Severity | Examples | Impact |
| --- | --- | --- |
| Severe | Missing title/meta/H1, bad canonical | Larger deductions |
| Soft | Title/meta length guidance, missing OG tags | Small deductions |
| Cross-page | Duplicate title or meta description | Modest deductions |

`scoreType` is always `custom_heuristic_v1`. It does **not** predict Google rankings or sales.

### Integrations & automation

**Use cases:** one-off store audits in Apify Console, scheduled crawls, CSV exports for agencies, and AI-assisted reviews where an assistant explains `issueDetails` in plain English.

**Apify MCP:** This Actor works with the [Apify MCP server](https://docs.apify.com/mcp) (`https://mcp.apify.com`), so compatible AI clients can search for, run, and read results from `mabelsays/shopify-seo-metadata-checker`. Claude setup is covered above; Apify also documents MCP connections for [ChatGPT](https://docs.apify.com/integrations/chatgpt) and [Cursor](https://docs.apify.com/integrations/cursor). You must authorize Apify and Actor runs; standard Actor charges (including **$0.004 per successfully audited page**) still apply.

**API / Zapier / Make / n8n:** Use the Apify API or client libraries to start a run with the same JSON input as Console. Results are available from the default dataset (`/items`) as JSON or CSV. Existing field names (`issues`, `score`, `titleOk`, duplicate flags, etc.) remain for compatibility; new guidance fields are additive.

### Limitations

- Works best on **public** Shopify HTML storefronts. Heavy bot protection may block some URLs (recorded as failed, not charged).
- Respects **robots.txt**; disallowed URLs are skipped.
- Polite defaults (concurrency 1 + delay) make large catalogs slower by design.
- Duplicate detection covers **only pages included in this audit**.
- Does not edit your theme or Shopify Admin.
- Structured data / JSON-LD is not scored in this version (metadata focus).
- Does not promise higher rankings or sales.

### FAQ

#### Do I need SEO experience?

No. Start with the **Store owner summary** dataset view and follow **Where to fix** for each top issue.

#### Is scraping Shopify stores allowed?

Only crawl storefronts you are allowed to access. Follow the site’s robots.txt and terms. This Actor is built for legitimate SEO audits of stores you own or have permission to analyze.

#### How is this different from a generic metadata scraper?

It is Shopify-aware (sitemap products/collections/pages), explains issues in plain English with Admin/theme fix paths, scores with a documented heuristic, and flags **cross-page duplicate** titles and meta descriptions within the run.

#### Why did I get fewer unique pages than max pages?

Duplicates (trailing slash / redirects), locale filtering, robots.txt skips, or failed fetches can reduce unique successful audits. Logs report attempted, succeeded, failed, and skippedDuplicates.

#### Do failed pages cost money under PPE?

**No.** Only the `audited-page` event is charged, and only for successful audits.

#### Can I run this on a schedule?

Yes — use Apify Schedules, then export the dataset or send it to your tools via integrations.

### Support

Open an Issue on the Actor page in Apify Console, or contact the developer through your Apify account messaging. Custom Shopify SEO workflows (bulk stores, agency dashboards) can be discussed on request.

### Development notes

```bash
npm install
npm test
apify validate-schema
apify run
```

Local input: `storage/key_value_stores/default/INPUT.json`.

# Actor input Schema

## `startUrls` (type: `array`):

Shopify storefront URL(s) to audit. Use the homepage (for example https://your-store.com). The Actor discovers products, collections, and pages from the store sitemap when available.

## `maxRequestsPerCrawl` (type: `integer`):

Maximum number of storefront pages to fetch and analyze in this run.

## `maxConcurrency` (type: `integer`):

How many pages to fetch in parallel. Keep at 1 for most Shopify stores to avoid rate limits (HTTP 429).

## `sameDomainDelaySecs` (type: `number`):

Minimum wait between requests to the same store. Default 2 seconds is polite and reduces blocking.

## `localeFilter` (type: `string`):

Limit the crawl to one language or market, for example en or en-us. Leave empty to scan all locales (full multilingual crawl). Unprefixed primary-market URLs are always included when a filter is set.

## `checkProducts` (type: `boolean`):

Discover and analyze URLs under /products/.

## `checkCollections` (type: `boolean`):

Discover and analyze URLs under /collections/.

## `checkPages` (type: `boolean`):

Discover and analyze URLs under /pages/ (About, Shipping, FAQ, and similar).

## `proxyConfiguration` (type: `object`):

Optional Apify Proxy. Leave disabled for most public Shopify storefronts. Do not use proxies to bypass site blocks or robots.txt.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://mabelloveco.com"
    }
  ],
  "maxRequestsPerCrawl": 50,
  "maxConcurrency": 1,
  "sameDomainDelaySecs": 2,
  "checkProducts": true,
  "checkCollections": true,
  "checkPages": true,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrls": [
        {
            "url": "https://mabelloveco.com"
        }
    ],
    "localeFilter": "",
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("mabelsays/shopify-seo-metadata-checker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startUrls": [{ "url": "https://mabelloveco.com" }],
    "localeFilter": "",
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("mabelsays/shopify-seo-metadata-checker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://mabelloveco.com"
    }
  ],
  "localeFilter": "",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call mabelsays/shopify-seo-metadata-checker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,mabelsays/shopify-seo-metadata-checker"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/SNAYqYiOfsSDlywc5/builds/rQzs0vKoNZ7627jlU/openapi.json