shopify-partners-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| SHOPIFY_PARTNER_ID | Yes | Partner Dashboard number. The number in your Partner Dashboard URL (the Dev Dashboard organization ID is different and does not work here). | |
| SHOPIFY_PARTNER_APP_IDS | No | Comma-separated app IDs for list_apps. IDs can be bare numbers or GIDs. | |
| SHOPIFY_PARTNER_API_VERSION | No | Shopify Partner API version. | 2026-07 |
| SHOPIFY_PARTNER_ACCESS_TOKEN | Yes | Partner API client token. Create a Partner API client in the Dev Dashboard with View financials and Manage apps permissions and copy the token. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Read-only access to one Shopify Partner organization.
Start with app_overview. For a question about one shop, use shop_history with its myshopify.com domain.
Analytics tools (app_overview, mrr_movement, earnings_by_month, retention_cohorts, trial_funnel, churn_report, plan_performance, customer_ltv, billing_watchlist) work from the app's full event history. The first call for an app downloads it, at four requests per second, and later calls reuse it for 15 minutes. Each result has a coverage block: when complete is false, the oldest data is missing and early months undercount.
Definitions:
Paying: installed, subscription not canceled or frozen, past its trial.
MRR: the flat-rate plan price of each paying shop, annual plans divided by 12. Usage charges are not MRR; earnings_by_month shows them.
Earnings: what Shopify pays you after its fee (net). Shopify calls this data analytics-grade, not accounting-grade.
Amounts are decimal strings per currency code, never converted.
IDs: tools accept a bare number or either GID form (gid://partners/... or gid://shopify/...) and convert as the API needs.
Raw tools (list_events, list_transactions, get_active_subscription, run_query) return one page and a nextCursor. run_query rejects mutations.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| app_overviewA | Start here. Where an app stands now (installed, paying, trialing, frozen, MRR, ARR) and what moved in the last 30 days. Without appId, compares every app in SHOPIFY_PARTNER_APP_IDS. Computed from the app's full event history, which the server downloads once and caches for 15 minutes. |
| mrr_movementA | Monthly recurring revenue per month with its movement: new, reactivation, expansion, contraction, and churn, in amounts and shop counts. MRR counts flat-rate subscription prices (annual plans divided by 12) of installed, non-frozen shops past their trial. Usage charges are not MRR; see earnings_by_month. Computed from the app's full event history, which the server downloads once and caches for 15 minutes. |
| earnings_by_monthA | What you actually earned per month: net, gross, and Shopify fee per currency, split by earning event type (recurring, usage, one-time, refund, credit, adjustment), plus upcoming settlements by date. Computed from the app's full event history, which the server downloads once and caches for 15 minutes. |
| retention_cohortsA | Shops grouped by the month they first installed. For each cohort: the percent still installed and the percent paying at the end of each later month. Computed from the app's full event history, which the server downloads once and caches for 15 minutes. |
| trial_funnelA | For shops that first installed in the range: how many subscribed, started a trial, paid, and pay now, with conversion rates and median days from install to first payment. Computed from the app's full event history, which the server downloads once and caches for 15 minutes. |
| churn_reportA | Uninstalls and subscription cancellations in the range: counts, uninstall reasons as Shopify reports them, scheduled cancellations, and each lost shop with its last plan and lifetime earnings, most valuable first. Computed from the app's full event history, which the server downloads once and caches for 15 minutes. |
| plan_performanceA | Per plan handle: paying and trialing shops now, MRR now, and in the range new subscriptions, cancellations, and moves in and out of the plan. Computed from the app's full event history, which the server downloads once and caches for 15 minutes. |
| customer_ltvA | Lifetime net earnings per paying shop: total, average, median, and top-ten share per currency, median paying days, and the ten highest-earning shops. Computed from the app's full event history, which the server downloads once and caches for 15 minutes. |
| billing_watchlistA | Shops that need attention now: frozen subscriptions, scheduled cancellations, deactivated stores, and credits not applied in the last 90 days. Facts only, no predictions. Computed from the app's full event history, which the server downloads once and caches for 15 minutes. |
| list_appsA | List the apps named in SHOPIFY_PARTNER_APP_IDS. The Partner API has no query that lists every app. |
| get_appB | Get an app's name and API key. |
| list_transactionsA | List earnings transactions (app, theme, service, referral, tax), newest first, one page at a time. Needs the View financials permission. |
| list_eventsA | List the historical event timeline: installs, uninstalls, subscription changes, charges, earnings, and credits. Needs the Manage apps permission. |
| get_active_subscriptionA | Get a shop's active subscription for an app that uses Shopify managed pricing. |
| revenue_summaryA | Total net, gross, and Shopify fees per currency, split by transaction type, for a time range. Reads up to 2,000 transactions. |
| install_summaryB | Count installs, uninstalls, deactivations, and reactivations per app for a time range. |
| shop_historyA | Everything about one shop for one app, newest first: install and billing events plus earnings transactions. Takes a shop ID or its myshopify.com domain. Useful for support questions. |
| run_queryA | Run a read-only GraphQL query against the Partner API for anything the other tools miss. Mutations are rejected. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 18 tools
Most tools have clearly distinct report targets (churn, MRR movement, cohorts, trial funnel, plan performance, LTV), and descriptions state scope precisely. However, earnings_by_month vs revenue_summary overlap substantially (both net/gross/Shopify fees per currency split by type, differing mainly in data source), and billing_watchlist vs churn_report both surface scheduled cancellations, which could cause misselection.
All names are snake_case, which keeps the set readable, but two conventions coexist: noun-phrase report names (churn_report, mrr_movement, retention_cohorts) and verb_noun API calls (list_apps, get_app, run_query). The split maps to a real distinction (analytics vs raw API), so it is a minor deviation rather than inconsistency.
18 tools is slightly heavy but justified by a broad domain spanning precomputed analytics, raw event/transaction access, and a GraphQL escape hatch. A few tools (revenue_summary, install_summary) partially duplicate what the richer reports provide, so the set could be trimmed marginally.
Coverage of the read-only analytics and financial surface is strong, including shop_history and run_query as catch-alls for gaps. Notable holes remain: there is no tool to list shops or discover shop IDs (shop_history requires an ID or domain you must already know), and no way to inspect app-level permissions or plan catalogs beyond per-plan performance.