Shopify Theme Inspector MCP

Ask your AI assistant why a Shopify theme is slow—and get a report that points to the Liquid files and lines worth fixing.

Shopify Theme Inspector MCP connects Shopify's server-side Liquid profiler to AI tools such as Codex, Claude Desktop, Cursor, Windsurf, and VS Code. It measures a live storefront, finds expensive templates and repeated work, compares pages, and turns flame-graph data into readable recommendations.

You do not need to be a programmer to run a report. If your AI app supports MCP, the setup is mostly copy, paste, sign in, and ask a question.

[!NOTE] This is an unofficial community project. It is not affiliated with or supported by Shopify.

Shopify store owner? Start here

This tool helps answer a practical question:

Which parts of my Shopify theme are making Shopify work harder before it can send the page to a customer?

You can ask that question in normal language. Your AI assistant runs the technical checks, reads Shopify's profiling data, and explains the findings without expecting you to understand a flame graph.

For example, a report can tell you that:

• A homepage section is doing a large amount of server-side work.
• The same product, menu, price, or image code is being rendered many times.
• A third-party app block appears frequently in the slowest part of the profile.
• A collection or product template deserves attention before less important code.
• A recent theme change improved, worsened, or did not meaningfully change Liquid render time.

The result is a prioritized investigation plan that you can understand yourself or give to a Shopify developer. It helps replace “the store feels slow” with evidence about which Liquid files, sections, snippets, and operations deserve attention.

[!IMPORTANT] The MCP diagnoses and explains potential theme bottlenecks. It does not automatically edit or publish your live theme. A theme developer should review, test, and deploy code changes safely—ideally on a duplicate theme first.

What does “MCP” mean?

MCP stands for Model Context Protocol. In simple terms, it is a way to give an AI assistant access to a specialized set of tools.

Without this MCP, an AI assistant cannot normally request your store's Shopify Liquid performance profile directly. With it, the assistant can run authorized, read-only profiling checks and discuss the results with you.

Think of it as a local bridge:

You ask a question
        ↓
Your AI assistant chooses the right inspection tool
        ↓
Shopify returns Liquid profiling data for the requested page
        ↓
The AI explains the evidence and suggests what to investigate

How it can help your Shopify business

Finding and correcting Liquid bottlenecks can reduce Shopify's server-side theme-rendering work. However, this tool does not promise a particular Lighthouse score, Core Web Vitals result, search ranking, or sales increase. Those outcomes also depend on images, JavaScript, apps, network conditions, customer devices, theme design, and many other factors.

What happens during an inspection?

1. You choose a page, such as the homepage, a collection, or a product.
2. You sign in to Shopify with an account authorized to access that store.
3. The MCP requests a read-only Liquid profile for the page.
4. Shopify returns timing data showing how the theme was rendered on the server.
5. Your AI assistant explains the profile and organizes the findings by likely importance.
6. You or your developer decide what to change. The MCP does not change the theme.
7. You run the profile again after a safe theme update to see whether the result improved.

For more reliable comparisons, profile the same page several times. Shopify infrastructure and cache state can cause normal variation between runs.

What can it inspect?

• Profile any page on a Shopify store you are authorized to inspect.
• Explain slow Liquid sections, snippets, blocks, tags, and app embeds.
• Point to relevant theme files and line numbers when Shopify provides them.
• Compare two pages or rank up to ten pages from slowest to fastest.
• Detect repeated rendering, expensive lookups, heavy templates, and other common patterns.
• Save profile history so you can measure whether a theme change helped.
• Export reports as Markdown, CSV, or Speedscope JSON.
• Read and explain the results through your AI assistant.

Profiling is read-only: it requests performance data from Shopify and does not edit or publish your theme.

Before you start

You need:

1. Node.js 18 or newer. Download the LTS version from nodejs.org if it is not installed.
2. Google Chrome or Chromium for Shopify sign-in.
3. An AI app that supports local MCP servers.
4. A Shopify account authorized to access the store you want to profile.

You do not need to download this repository when using the npm package.

npm package details

The MCP is published as a public package on npm, so supported AI applications can download and start it for you.

The examples below use npx -y shopify-theme-inspector-mcp@latest. npx downloads the public package when needed and starts the MCP locally. You do not need a global installation, a cloned repository, or an npm account.

To check the newest published version:

npm view shopify-theme-inspector-mcp version

Using @latest automatically selects the current npm release. Teams that require repeatable environments can replace it with a fixed version, such as shopify-theme-inspector-mcp@0.5.1.

Connect to Codex

Open a terminal and run:

codex mcp add shopify-theme-inspector -- npx -y shopify-theme-inspector-mcp@latest

Restart Codex. You can confirm the server is registered with:

codex mcp list

Then ask:

Use the shopify-theme-inspector health_check tool and show me the result.

Codex stores local MCP configuration in ~/.codex/config.toml. The Codex app, CLI, and IDE extension share that configuration on the same Codex host. You can also add the server through Settings → MCP servers in supported Codex interfaces. See the official Codex MCP documentation for current configuration options.

Connect to Claude Code

Open a terminal and run:

claude mcp add --transport stdio --scope user shopify-theme-inspector -- npx -y shopify-theme-inspector-mcp@latest

The --scope user option makes the MCP available across your Claude Code projects. Confirm the connection with:

claude mcp list

Inside Claude Code, you can also run /mcp to view the server and its tools. Then ask:

Use the shopify-theme-inspector health_check tool and explain the result.

See the official Claude Code MCP documentation for scopes, server management, and troubleshooting.

Connect to Claude Desktop

Claude Desktop can run this package as a local MCP server on macOS or Windows:

1. Install Node.js 18 or newer.
2. Open Claude Desktop → Settings → Developer → Edit Config.
3. Add the configuration below inside the mcpServers object.
4. Save the file, fully quit Claude Desktop, and reopen it.

{
  "mcpServers": {
    "shopify-theme-inspector": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "shopify-theme-inspector-mcp@latest"]
    }
  }
}

If you already have other MCP servers, keep them and add only the shopify-theme-inspector entry. Do not create a second mcpServers object.

After restarting, open the Connectors menu from the + button in the chat box to confirm the tools are available. Then ask Claude:

Use Shopify Theme Inspector health_check and explain whether everything is ready.

The configuration file is normally located at:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

See the official MCP guide for connecting local servers to Claude Desktop.

Setup in other MCP apps