flin-shopify-analytics-mcp

Read-only MCP server for Shopify analytics.

Der Server ist dafür gedacht, Shopify-Shop-Daten in Claude oder anderen MCP-Clients lesend abzufragen, zum Beispiel:

• Welche Kunden haben bestellt?
• Welche Produkte wurden gekauft?
• Wie viele Einheiten wurden gekauft?
• Wie viel Umsatz hat ein Kunde erzeugt?

Was dieser MCP kann

Der Server stellt diese Tools bereit:

• Basisdaten:

• shopify_list_orders

• shopify_list_customers

• shopify_list_products

• shopify_customer_purchase_summary

• shopify_sales_by_customer_product

• Reporting Core (v2, auf main):

• shopify_sales_overview

• shopify_sales_timeseries

• shopify_top_products

• shopify_top_customers

• shopify_discount_analysis

• Retention / CRM Health (v3, auf main):

• shopify_retention_overview

• shopify_repeat_purchase_windows

• shopify_time_to_second_order

• shopify_inactive_customer_summary

• Attribution (v4, auf main):

• shopify_attribution_quality_summary

• shopify_sales_by_source

• shopify_sales_by_utm

• shopify_new_customers_by_attribution

• shopify_landing_page_analysis

Write-Operationen sind nicht erlaubt. GraphQL-Mutationen werden blockiert.

Wichtig: Ohne Shopify-App funktioniert dieser MCP nicht

Du brauchst für den Ziel-Shop immer eine installierte Shopify-App mit Admin-API-Rechten.

Je nach App-Typ bekommst du unterschiedliche Credentials:

• Neue Apps ab 2026: Client ID + Client Secret
• Bestehende Legacy-Custom-Apps: Admin API access token (shpat_...)

Ohne installierte App und passende Scopes kann der MCP keine Orders, Kunden oder Produkte lesen.

Voraussetzungen

• Python 3.10+
• uv oder uvx
• Zugriff auf den Shopify-Store
• Berechtigung, eine App für den Store zu erstellen und zu installieren

Shopify-App erstellen

Empfohlen: Dev Dashboard App mit Client Credentials

Das ist der richtige Weg für neue Shopify-Apps.

1. Öffne den Shopify Dev Dashboard Bereich für deine App.
2. Erstelle eine App für den Ziel-Store.
3. Konfiguriere die Admin-API-Scopes.
4. Release die App-Version mit diesen Scopes.
5. Installiere die App auf dem Store.
6. Öffne in der App Settings und kopiere:
   • Client ID
   • Client secret

Für diesen MCP brauchst du mindestens diese Scopes:

• read_products
• read_customers
• read_orders

Optional:

• read_all_orders

read_all_orders ist sinnvoll, wenn du nicht nur die normalen Standard-Zeiträume von Shopify auslesen willst. Für v3 Retention-KPIs ist read_all_orders faktisch empfohlen, weil Wiederkauf- und Inaktivitätskennzahlen sonst auf unvollständiger Historie basieren können. Für v4 Neukunden-Attribution ist read_all_orders ebenfalls empfohlen, weil der MCP dafür die erste bekannte Bestellung eines Kunden bis dateTo korrekt erkennen muss.

Legacy: Bestehende Custom App im Shopify Admin

Nur für bereits existierende Admin-Custom-Apps.

1. Öffne die bestehende Custom App im Shopify Admin.
2. Stelle sicher, dass die App installiert ist.
3. Prüfe die Admin-API-Scopes.
4. Kopiere den Admin API access token.

Auch hier brauchst du mindestens:

• read_products
• read_customers
• read_orders

Welche Credentials du eintragen musst

Option A: Dev Dashboard App

Verwende diese Variablen:

SHOPIFY_STORE_DOMAIN="your-store.myshopify.com"
SHOPIFY_CLIENT_ID="your_client_id"
SHOPIFY_CLIENT_SECRET="your_client_secret"
SHOPIFY_API_VERSION="2026-04"

Der MCP holt das Access Token automatisch über den Client-Credentials-Flow und erneuert es selbst.

Option B: Legacy Custom App

Verwende diese Variablen:

SHOPIFY_STORE_DOMAIN="your-store.myshopify.com"
SHOPIFY_ADMIN_ACCESS_TOKEN="shpat_xxx"
SHOPIFY_API_VERSION="2026-04"

Wenn SHOPIFY_ADMIN_ACCESS_TOKEN gesetzt ist, verwendet der MCP den statischen Token-Modus.

Claude Desktop Konfiguration

Empfohlener Skill fuer Analysen

Wenn du diesen MCP in Claude oder Codex fuer schnelle Shop-Analysen nutzt, ist es empfohlen, zusaetzlich den repo-lokalen Skill zu verwenden:

• skills/shopify-analysis-playbook/SKILL.md

Der Skill ist kein Ersatz fuer den MCP. Er ist ein Analyse-Playbook, das Claude hilft:

• die richtigen Tools in der richtigen Reihenfolge zu nutzen
• Antworten kurz und entscheidungsorientiert zu halten
• Attribution und Retention nicht zu ueberinterpretieren

Empfohlene Kombination:

1. MCP verbinden
2. Skill laden bzw. referenzieren
3. Dann Fragen stellen wie:
   • "Give me a 30-day executive sales snapshot"
   • "Why did revenue drop vs the previous period?"
   • "Is retention healthy?"
   • "Can we trust the attribution data?"

Variante 1: Über PyPI mit uvx

Die Beispiele unten sind auf die letzte veröffentlichte PyPI-Version gepinnt. main kann bereits zusätzliche, noch nicht veröffentlichte Tools enthalten.

{
  "mcpServers": {
    "flin-shopify-analytics-mcp": {
      "command": "uvx",
      "args": [
        "--refresh",
        "-q",
        "flin-shopify-analytics-mcp@0.3.0"
      ],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret",
        "SHOPIFY_API_VERSION": "2026-04"
      }
    }
  }
}

Variante 2: Lokal aus dem Repo

Das ist die stabilste Variante für Entwicklung und Debugging.

{
  "mcpServers": {
    "flin-shopify-analytics-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--quiet",
        "--directory",
        "/Users/nicolasg/Antigravity/flin-shopify-analytics-mcp",
        "flin-shopify-analytics-mcp"
      ],
      "env": {
        "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com",
        "SHOPIFY_CLIENT_ID": "your_client_id",
        "SHOPIFY_CLIENT_SECRET": "your_client_secret",
        "SHOPIFY_API_VERSION": "2026-04"
      }
    }
  }
}

Lokaler Start ohne Claude

Mit Client ID / Client Secret

uvx --refresh -q flin-shopify-analytics-mcp@0.3.0 \
  --domain your-store.myshopify.com \
  --clientId your_client_id \
  --clientSecret your_client_secret \
  --apiVersion 2026-04

Mit statischem Admin-Token

uvx --refresh -q flin-shopify-analytics-mcp@0.3.0 \
  --domain your-store.myshopify.com \
  --accessToken shpat_xxx \
  --apiVersion 2026-04

TLS / SSL

Der MCP verwendet standardmäßig das certifi-CA-Bundle.

Falls deine Umgebung einen Firmen-Proxy oder eigene Root-Zertifikate benutzt, kannst du zusätzlich setzen:

SHOPIFY_CA_BUNDLE="/path/to/ca-bundle.pem"

Alternativ funktioniert auch:

SSL_CERT_FILE="/path/to/ca-bundle.pem"

Troubleshooting

Attribution-Daten sind leer oder unvollständig

Die v4 Attribution-Tools basieren auf Shopify-Order-Attribution und Customer Journey Daten.

Wichtig:

1. Shopify-Attribution ist nicht für jede Order vollständig vorhanden.
2. shopify_attribution_quality_summary zeigt dir zuerst, wie viele Orders überhaupt Source-, Landing-Page- oder UTM-Daten haben.
3. shopify_sales_by_source und shopify_sales_by_utm reporten fehlende Daten bewusst als unattributed oder <none>, statt Werte zu raten.
4. shopify_new_customers_by_attribution und shopify_landing_page_analysis mit newCustomers sind am belastbarsten, wenn die App read_all_orders hat.

SSL: CERTIFICATE_VERIFY_FAILED

Dann kann die Python-Umgebung die Zertifikatskette nicht verifizieren.

Prüfe in dieser Reihenfolge:

1. Ob du auf 0.3.0 oder neuer bist
2. Ob ein Firmen-Proxy oder eigenes Root-CA im Spiel ist
3. Ob SHOPIFY_CA_BUNDLE oder SSL_CERT_FILE gesetzt werden muss

no version of flin-shopify-analytics-mcp == ...

Dann hängt uvx meistens noch auf einem alten Index-Stand.

Hilfreich:

uv cache clean flin-shopify-analytics-mcp

Und in der Claude-Konfiguration:

"args": ["--refresh", "-q", "flin-shopify-analytics-mcp@0.3.0"]

Entwicklung

Tests:

python -m unittest discover -s py_tests -v

Build:

uv build

Release

1. Version in pyproject.toml, flin_shopify_analytics_mcp/__init__.py und flin_shopify_analytics_mcp/mcp_server.py anheben
2. Commit erstellen
3. Tag vX.Y.Z pushen
4. GitHub Actions Workflow .github/workflows/release.yml veröffentlicht auf PyPI

Offizielle Shopify-Doku

• Dev Dashboard App und Client Credentials: https://shopify.dev/docs/apps/build/dev-dashboard/get-api-access-tokens
• Legacy Custom Apps im Shopify Admin: https://shopify.dev/docs/apps/build/authentication-authorization/access-tokens/generate-app-access-tokens-admin