shopify-partners-mcp
Read-only access to the Shopify Partner API for your apps: lists apps and fetches earnings/transactions, the event timeline (installs, uninstalls, subscription changes, charges, credits), and active subscriptions. Also provides analytics tools that answer business questions such as MRR movement, earnings by month, retention cohorts, trial funnel conversion, churn, plan performance, customer LTV, and a billing watchlist, plus a run_query tool for arbitrary read-only GraphQL queries against the Partner API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@shopify-partners-mcp Show me last month's MRR movement for my Shopify apps."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
shopify-partners-mcp
An MCP server for the Shopify Partner API. It lets an AI client read your apps, earnings, install and billing events, and subscriptions. It is read-only: no tool changes anything in your Partner account.
Tools
Analytics
These tools answer business questions directly. The first call for an app downloads its full event history (one year per step, until a year has no events). Later calls reuse it for 15 minutes. Every result has a coverage block that says how far back the data goes.
Tool | What it answers |
| Where an app stands now (installed, paying, trialing, frozen, MRR, ARR) and the last 30 days. Without |
| MRR per month, split into new, reactivation, expansion, contraction, and churn |
| Net, gross, and Shopify fee per month by earning type, plus upcoming settlements |
| Percent of each install-month cohort still installed and still paying, month by month |
| Installs, then subscriptions, then trials, then first payment, with conversion rates |
| Uninstalls and cancellations with Shopify's uninstall reasons, scheduled cancellations, and the most valuable shops lost |
| Per plan: paying and trialing shops, MRR, new subscriptions, cancellations, and moves between plans |
| Lifetime net earnings per paying shop, top-ten share, and the highest-earning shops |
| Frozen subscriptions, scheduled cancellations, deactivated stores, and credits not applied |
Definitions:
Paying: installed, subscription not canceled or frozen, and past its trial.
MRR: the flat-rate plan price of each paying shop. Annual plans count as one twelfth. Usage charges are not MRR;
earnings_by_monthshows them.Amounts stay in their own currency. The server never converts them.
Raw data
Tool | What it returns |
| The apps you list in |
| One app's name and API key |
| Earnings: app, theme, service, referral, and tax transactions |
| The event timeline: installs, uninstalls, subscription changes, charges, earnings, credits |
| A shop's active subscription, for apps on Shopify managed pricing |
| Net, gross, and Shopify fees per currency, split by transaction type |
| Installs, uninstalls, deactivations, and reactivations per app |
| One shop's events and transactions in one timeline, by shop ID or myshopify.com domain |
| Any read-only GraphQL query, for what the other tools miss |
List tools return one page and a nextCursor. Summary tools read up to 2,000 rows and set truncated when there were more. When SHOPIFY_PARTNER_APP_IDS names one app, appId is optional everywhere.
Related MCP server: shopify
Setup
In the Dev Dashboard, open Organization settings > Users > Security > Partner API clients and add a client. Give it View financials and Manage apps. Copy the token; it is shown once.
Find your Partner ID: the number in your Partner Dashboard URL. The Dev Dashboard organization ID is a different number and does not work here.
Add the server to your MCP client:
{
"mcpServers": {
"shopify-partners": {
"command": "npx",
"args": ["-y", "shopify-partners-mcp"],
"env": {
"SHOPIFY_PARTNER_ID": "1234567",
"SHOPIFY_PARTNER_ACCESS_TOKEN": "prtapi_...",
"SHOPIFY_PARTNER_APP_IDS": "1234,5678"
}
}
}
}To run from source instead, build it and set command to node with args ["/path/to/shopify-partners-mcp/dist/index.js"].
Variable | Required | Notes |
| Yes | Partner Dashboard number |
| Yes | Partner API client token |
| No | Comma-separated app IDs for |
| No | Defaults to |
IDs can be bare numbers or GIDs. The server converts them, because the API wants gid://partners/... for some fields and gid://shopify/... for others.
Limits
Shopify allows four requests per second per API client. The server spaces requests and retries when Shopify returns 429.
The event timeline covers at most 365 days per request and defaults to the last 30 days. The analytics tools step through it a year at a time for you.
Filtering events by shop needs an app ID.
shop_historyfills it in from your config.Shopify may not have turned on the event timeline for every organization. If it is off, the analytics tools return Shopify's error.
Shopify says transaction data is for analytics, not accounting.
Development
mise install
pnpm install
pnpm check # lint, types, unused code, tests
pnpm build
pnpm smoke # start the built server and list its toolsPR titles must be Conventional Commits; release-please builds versions and the changelog from them. See docs/releasing.md.
License
MIT
Available Tools
18 toolsapp_overviewARead-only
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.
Inputs: appId.
billing_watchlistARead-only
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.
Inputs: appId.
churn_reportARead-only
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.
Inputs: to, from, appId.
customer_ltvARead-only
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.
Inputs: appId.
earnings_by_monthARead-only
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.
Inputs: appId, months.
get_active_subscriptionARead-only
Get a shop's active subscription for an app that uses Shopify managed pricing.
Inputs: appId (required), shopId (required).
get_appBRead-only
Get an app's name and API key.
Inputs: appId (required).
install_summaryBRead-only
Count installs, uninstalls, deactivations, and reactivations per app for a time range.
Inputs: appId, occurredAtMax, occurredAtMin.
list_appsARead-only
List the apps named in SHOPIFY_PARTNER_APP_IDS. The Partner API has no query that lists every app.
Inputs: no named parameters.
list_eventsARead-only
List the historical event timeline: installs, uninstalls, subscription changes, charges, earnings, and credits. Needs the Manage apps permission.
Inputs: after, appId, first, shopId, +3 more.
list_transactionsARead-only
List earnings transactions (app, theme, service, referral, tax), newest first, one page at a time. Needs the View financials permission.
Inputs: after, appId, first, types, +4 more.
mrr_movementARead-only
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.
Inputs: appId, months.
plan_performanceARead-only
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.
Inputs: to, from, appId.
retention_cohortsARead-only
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.
Inputs: appId, months.
revenue_summaryARead-only
Total net, gross, and Shopify fees per currency, split by transaction type, for a time range. Reads up to 2,000 transactions.
Inputs: appId, types, shopId, createdAtMax, +2 more.
run_queryARead-only
Run a read-only GraphQL query against the Partner API for anything the other tools miss. Mutations are rejected.
Inputs: query (required), variables.
shop_historyARead-only
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.
Inputs: shop (required), appId, occurredAtMax, occurredAtMin.
trial_funnelARead-only
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.
Inputs: to, from, appId.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Read-only analytics for your Shopify apps: MRR, churn, uninstall reasons, App Store rank, reviews.
Lets AI agents analyze API metrics, request logs, and traces, and manage apps and alerts.
Amazon Ads, Seller Central, Vendor Central and AMC data for AI agents. Read-only by default.
Read-only analytics for all your apps: users, AI traffic, revenue, with the SQL behind every number.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides AI assistants with real-time access to Shopify store analytics, sales data, and inventory through ShopifyQL and the Admin GraphQL API. It enables users to query store performance, customer metrics, and marketing insights using natural language.13MIT
- AlicenseAqualityCmaintenanceEnables AI agents to read and write Shopify store data including products, orders, customers, inventory, and more via the Admin GraphQL API.2858 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to query Shopify analytics with ShopifyQL via the Admin GraphQL endpoint, executing queries and interpreting results like 'show me the products with the highest margins'.-
- AlicenseAqualityCmaintenanceEnables AI agents to query Stripe operations such as customers, recent charges, duplicate charges, and revenue summaries through read-only MCP tools.4MIT