{"id":50965965,"url":"https://github.com/rushikeshmore/shopify-partner-agent","last_synced_at":"2026-06-18T20:32:34.969Z","repository":{"id":344638803,"uuid":"1182536355","full_name":"rushikeshmore/shopify-partner-agent","owner":"rushikeshmore","description":"MCP server for Shopify Partner API analytics - 25 tools for MRR, churn, retention, merchant health, forecasting. Free and open source.","archived":false,"fork":false,"pushed_at":"2026-04-15T15:36:01.000Z","size":208,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T16:36:51.096Z","etag":null,"topics":["claude","mcp","mcp-server","partner-api","python","saas-metrics","shopify","shopify-app","shopify-partner","shopify-partner-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rushikeshmore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-15T16:48:23.000Z","updated_at":"2026-04-15T16:08:36.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rushikeshmore/shopify-partner-agent","commit_stats":null,"previous_names":["rushikeshmore/partner-agent","rushikeshmore/shopify-partner-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rushikeshmore/shopify-partner-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rushikeshmore%2Fshopify-partner-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rushikeshmore%2Fshopify-partner-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rushikeshmore%2Fshopify-partner-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rushikeshmore%2Fshopify-partner-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rushikeshmore","download_url":"https://codeload.github.com/rushikeshmore/shopify-partner-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rushikeshmore%2Fshopify-partner-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34507156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","mcp","mcp-server","partner-api","python","saas-metrics","shopify","shopify-app","shopify-partner","shopify-partner-api"],"created_at":"2026-06-18T20:32:33.836Z","updated_at":"2026-06-18T20:32:34.950Z","avatar_url":"https://github.com/rushikeshmore.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shopify Partner Agent\n\n[![PyPI](https://img.shields.io/pypi/v/shopify-partner-agent.svg)](https://pypi.org/project/shopify-partner-agent/)\n[![CI](https://github.com/rushikeshmore/shopify-partner-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/rushikeshmore/shopify-partner-agent/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/Python-3.11+-3776ab.svg)](https://python.org)\n[![MCP Tools: 25](https://img.shields.io/badge/MCP_Tools-25-96bf48.svg)](#tools)\n\nFree, open-source MCP server that connects Claude to the Shopify Partner API. 25 tools for revenue analytics, churn analysis, retention cohorts, merchant health scoring, conversion funnels, revenue forecasting, and growth velocity.\n\nQuery your app business in natural language. No dashboards, no monthly fees.\n\n## Why This Exists\n\nShopify's own [AI Toolkit](https://github.com/Shopify/Shopify-AI-Toolkit) and official MCP servers ([Dev MCP](https://www.npmjs.com/package/@shopify/dev-mcp), Storefront MCP, Customer Account MCP, Checkout MCP) all target the **Admin API** and **Storefront API**, which cover store operations and shopping experiences. Every third-party Shopify MCP server on GitHub does the same.\n\n**None of them connect to the Partner API.** If you build Shopify apps, your revenue metrics, churn data, and merchant analytics are locked behind the Partner Dashboard with no MCP-compatible way to query them.\n\nShopify Partner Agent is the only MCP server that gives AI tools access to Partner API analytics: MRR, churn, retention cohorts, merchant health, and 20 more computed metrics that even the raw API doesn't provide.\n\nAsk Claude things like:\n- \"What's my MRR and how has it changed this quarter?\"\n- \"Who uninstalled my app this month and why?\"\n- \"Show me retention cohorts for the last 6 months\"\n- \"Which merchants are at high risk of churning?\"\n- \"Give me a weekly business digest\"\n- \"Compare all my apps side by side\"\n\n## Tools\n\n### Core Data (5)\n| Tool | What it does |\n|------|-------------|\n| `discover_apps` | Find all apps in your partner account (from config + transaction history) |\n| `get_app_details` | App name, GID, and API key for a specific app |\n| `get_app_events` | Install, uninstall, charge, credit events with date filtering |\n| `get_transactions` | Revenue transactions filtered by app, type, and date range |\n| `get_merchants` | Active, churned, or all merchants with install dates and uninstall reasons |\n\n### Revenue Analytics (4)\n| Tool | What it does |\n|------|-------------|\n| `get_revenue_summary` | MRR, ARR, total revenue, growth rate, ARPU, breakdown by app and currency |\n| `get_mrr_movement` | New, expansion, contraction, churn, and reactivation MRR breakdown |\n| `get_payout_report` | Gross revenue, Shopify fees, net payout with per-type breakdown |\n| `get_plan_performance` | Subscribers, revenue, and avg revenue per pricing tier |\n\n### Customer Analytics (4)\n| Tool | What it does |\n|------|-------------|\n| `get_churn_analysis` | Revenue churn %, logo churn %, uninstall reason breakdown |\n| `get_retention_cohorts` | Monthly revenue retention cohort table (values above 100% = expansion) |\n| `get_customer_ltv` | LTV, ARPU, average lifespan, top and bottom 5 merchants by revenue |\n| `get_churned_merchants` | Recent uninstalls with dates and reasons, sorted most recent first |\n\n### Growth \u0026 Forecasting (6)\n| Tool | What it does |\n|------|-------------|\n| `get_trial_funnel` | Install-to-paid conversion rate, timing analysis, converted/unconverted lists |\n| `get_growth_velocity` | Week-over-week install/uninstall/revenue trends with acceleration signals |\n| `get_install_patterns` | Best day of week and time of month for installs, monthly trend |\n| `get_revenue_forecast` | Project MRR for next 3-6 months based on historical growth rate |\n| `get_referral_revenue` | Shopify merchant referral revenue with period comparison |\n| `get_credits_adjustments` | Refunds, credits, adjustments with giveback percentage |\n\n### Merchant Intelligence (4)\n| Tool | What it does |\n|------|-------------|\n| `get_churn_risk` | Score active merchants by churn risk (low/medium/high) with contributing factors |\n| `get_merchant_health` | Composite health grade (A-F) based on tenure, revenue, stability, engagement |\n| `get_merchant_lookup` | Full chronological timeline for a specific merchant (events + transactions) |\n| `get_business_digest` | Weekly or monthly summary with highlights and period-over-period comparison |\n\n### Multi-App (2)\n| Tool | What it does |\n|------|-------------|\n| `get_revenue_anomalies` | Detect unusual revenue patterns using statistical deviation |\n| `get_app_comparison` | Side-by-side metrics (revenue, installs, churn, ARPU) across all apps |\n\n## Install\n\n**Before you start, you need:**\n- A [Shopify Partner account](https://partners.shopify.com).\n- An MCP client installed: [Claude Desktop](https://claude.ai/download), [Claude Code](https://claude.ai/download), [Cursor](https://www.cursor.com), or [Windsurf](https://codeium.com/windsurf). Claude Desktop is free and takes two minutes to install if you don't have one yet.\n\n### 1. Get your Partner API credentials\n\nYou need three values. Log in to the [Partners Dashboard](https://partners.shopify.com) first, then collect each one below.\n\n**`SHOPIFY_ORG_ID`**\n\nThe number in your Dashboard URL. Once you are logged in, look at the address bar:\n\n```\nhttps://partners.shopify.com/1234567/...\n                             ^^^^^^^  this is your org ID\n```\n\n**`SHOPIFY_ACCESS_TOKEN`**\n\n1. Open **Settings \u003e Partner API clients** in the Dashboard.\n2. Click **Create API client**.\n3. Grant permissions: **Manage apps** and **View financials**.\n4. Copy the token. It is shown only once, so save it somewhere safe.\n\n**`SHOPIFY_APP_IDS`**\n\nOne entry per app you want to query, comma-separated.\n\n1. Open **Apps** in the Dashboard and click an app.\n2. The URL ends with a numeric ID, for example `/apps/9876543`.\n3. Format it as a GID: `gid://partners/App/9876543`. Bare numeric IDs also work.\n4. Multiple apps? Join them with commas: `gid://partners/App/1,gid://partners/App/2`.\n\n### 2. Add the server to your MCP client\n\nYour MCP client will install and run the server automatically the first time it launches. You don't need to download, clone, or set up anything yourself.\n\n\u003cdetails\u003e\n\u003csummary\u003eWhat actually gets installed?\u003c/summary\u003e\n\nThe config you paste below tells your MCP client to run a command called `uvx`. On first launch, `uvx` fetches the server from the Python package registry ([PyPI](https://pypi.org/project/shopify-partner-agent/)) and stores it in a local folder on your computer. After that, startup is instant.\n\n**Where the files sit:**\n- **macOS / Linux:** `~/.cache/uv/`\n- **Windows:** `%LOCALAPPDATA%\\uv\\cache\\`\n\nThe installed package contains only the server code. It does not include your credentials, any test files, or anything else from your machine. The source is public on [PyPI](https://pypi.org/project/shopify-partner-agent/) and [GitHub](https://github.com/rushikeshmore/shopify-partner-agent), so you can audit exactly what runs.\n\n**Remove the installed copy later:**\n```bash\nuv cache clean shopify-partner-agent\n```\n\n**Update to the latest release:** run the command above, then restart your MCP client. It fetches the newest version on the next launch.\n\nPrefer a traditional install you can see on disk? Use the **pip install** option further down, or `git clone` the repo and run `uv sync`.\n\n\u003c/details\u003e\n\n**Claude Desktop** is the most common path. Paste the block below into `claude_desktop_config.json` and swap in the three values from step 1:\n\n```json\n{\n  \"mcpServers\": {\n    \"shopify-partner-agent\": {\n      \"command\": \"uvx\",\n      \"args\": [\"shopify-partner-agent\"],\n      \"env\": {\n        \"SHOPIFY_ORG_ID\": \"your_org_id\",\n        \"SHOPIFY_ACCESS_TOKEN\": \"your_token\",\n        \"SHOPIFY_APP_IDS\": \"gid://partners/App/1234567\"\n      }\n    }\n  }\n}\n```\n\nConfig file location:\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\nIf the file does not exist yet, create it with the block above exactly as shown. If it already contains other MCP servers, add `shopify-partner-agent` inside the existing `mcpServers` object.\n\nUsing a different client? Open the matching section below.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/summary\u003e\n\nOne command from your terminal:\n\n```bash\nclaude mcp add shopify-partner-agent uvx shopify-partner-agent \\\n  -e SHOPIFY_ORG_ID=your_org_id \\\n  -e SHOPIFY_ACCESS_TOKEN=your_token \\\n  -e SHOPIFY_APP_IDS=gid://partners/App/1234567\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor / Windsurf\u003c/b\u003e\u003c/summary\u003e\n\nSame JSON as Claude Desktop. Open the MCP settings panel and paste the block below.\n\n- **Cursor:** Settings \u003e **MCP** \u003e **Add new global MCP server**, or edit `~/.cursor/mcp.json` directly.\n- **Windsurf:** Settings \u003e **Cascade** \u003e **MCP servers**.\n\n```json\n{\n  \"mcpServers\": {\n    \"shopify-partner-agent\": {\n      \"command\": \"uvx\",\n      \"args\": [\"shopify-partner-agent\"],\n      \"env\": {\n        \"SHOPIFY_ORG_ID\": \"your_org_id\",\n        \"SHOPIFY_ACCESS_TOKEN\": \"your_token\",\n        \"SHOPIFY_APP_IDS\": \"gid://partners/App/1234567\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003epip install (if you don't use uvx)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\npip install shopify-partner-agent\n```\n\nThen update your MCP config to call the installed command directly instead of `uvx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"shopify-partner-agent\": {\n      \"command\": \"shopify-partner-agent\",\n      \"env\": {\n        \"SHOPIFY_ORG_ID\": \"your_org_id\",\n        \"SHOPIFY_ACCESS_TOKEN\": \"your_token\",\n        \"SHOPIFY_APP_IDS\": \"gid://partners/App/1234567\"\n      }\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003ePrefer an AI to set it up for you? Paste this prompt\u003c/b\u003e\u003c/summary\u003e\n\nOpen any LLM chat and paste the prompt below. It asks which client you use and generates the exact config file path and JSON for you.\n\n```\nI want to install the shopify-partner-agent MCP server. It is a Python package on PyPI that connects AI assistants to the Shopify Partner API for revenue, churn, cohort, and merchant analytics.\n\nWalk me through setup step by step:\n\n1. Ask which MCP client I use: Claude Desktop, Claude Code, Cursor, or Windsurf.\n2. Explain how to create a Shopify Partner API access token: Partners Dashboard \u003e Settings \u003e Partner API clients \u003e Create API client. Required scopes: \"Manage apps\" and \"View financials\". The token is shown only once, so I need to copy it.\n3. Explain how to find my app GIDs. The format is gid://partners/App/1234567 and the numeric ID is visible in the Partners Dashboard URL when I open an app.\n4. Generate the MCP config for the client I picked. Use the command \"uvx\" with args [\"shopify-partner-agent\"] and these placeholder env vars: SHOPIFY_ORG_ID=\u003cmy_org_id\u003e, SHOPIFY_ACCESS_TOKEN=\u003cmy_token\u003e, SHOPIFY_APP_IDS=\u003ccomma_separated_app_gids\u003e.\n5. Tell me the exact config file path for my client on macOS and Windows, and where in that file the mcpServers section goes.\n6. Tell me to replace the placeholders on my own machine. Do NOT ask me to paste my real token into this chat.\n7. Tell me to fully quit and relaunch the MCP client, then confirm the 25 shopify-partner-agent tools appear.\n\nReference: https://github.com/rushikeshmore/shopify-partner-agent\nPackage:   https://pypi.org/project/shopify-partner-agent/\n```\n\n\u003e **Keep your access token out of chat.** Generate the config with placeholders, then fill in the real token locally.\n\n\u003c/details\u003e\n\n### 3. Restart your MCP client and verify\n\nSave the config, then **fully quit and relaunch** your MCP client. Most clients only read config at startup, so a window reload will not pick it up. After the client restarts, look for `shopify-partner-agent` in the tools or MCP menu. It should appear as connected with 25 tools. If something is off, see [Troubleshooting](#troubleshooting).\n\n### 4. Start using it\n\n```\n\u003e Show me my Shopify apps\n\u003e What's my churn rate this month?\n\u003e Who uninstalled recently and why?\n\u003e Give me a full health check of my app business\n\u003e Score my merchants by churn risk\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eTroubleshooting\u003c/b\u003e\u003c/summary\u003e\n\n**`missing required env vars: SHOPIFY_ORG_ID, ...`**\nCredentials aren't reaching the server. Double-check the `env` block in your MCP client config above, then fully restart the client.\n\n**`401 Unauthorized` or token errors**\nThe access token is wrong or missing scopes. Recreate it in Partners Dashboard with **Manage apps** + **View financials** and update your config.\n\n**App ID format errors**\nApp IDs must be GIDs: `gid://partners/App/1234567`. Bare numeric IDs won't work. Copy the correct format from the Partners Dashboard URL when you open the app.\n\n**Tools don't show up in Claude Desktop, Cursor, or Windsurf**\nFully quit and relaunch the MCP client after editing config. Most clients only read config at startup.\n\n**`uvx` is stuck on an old version after a release**\nClear the cache and retry: `uv cache clean shopify-partner-agent`.\n\n\u003c/details\u003e\n\n## Analytics Formulas\n\nAll formulas match industry-standard SaaS metrics:\n\n| Metric | Formula |\n|--------|---------|\n| MRR | Event-aware: subscription + usage MRR per active merchant (annual / 12, usage trailing 30d). Two-track status model: relationship (installed/uninstalled) + subscription (frozen/canceled/expired). Falls back to charge-based when events unavailable. |\n| Net New MRR | New + Reactivation + Expansion - Contraction - Churn |\n| Quick Ratio | (New + Expansion + Reactivation) / (Contraction + Churn) |\n| Reactivation MRR | Revenue from previously-churned merchants who reinstalled |\n| Revenue Churn % | (Churned MRR + Contraction) / Starting MRR x 100 |\n| Logo Churn % | Uninstalled merchants / Starting merchants x 100 |\n| LTV | ARPU x Average lifespan |\n| ARPU | Total net revenue / Active merchants (excludes churned when events available) |\n| Retention | Revenue in month N / Revenue in month 0 (per cohort) |\n| Health Score | Tenure (0-25) + Revenue (0-25) + Stability (0-25) + Engagement (0-25) |\n| Churn Risk | 5 heuristic signals: deactivations, cancellations, reinstalls, declining charges, inactivity |\n| Growth Velocity | Week-over-week install/revenue trends, revenue grouped by currency |\n\n## Requirements\n\n- Python 3.11+\n- Shopify Partner account with API access\n- Any MCP-compatible client (Claude Code, Claude Desktop, Cursor, Windsurf)\n\n## Data Privacy\n\n- **Direct API access.** All Partner API calls go from your machine to Shopify. No proxy, no intermediate server, no cloud component operated by this project.\n- **No telemetry.** This server does not send usage, analytics, or error data anywhere. If you block every network except `partners.shopify.com`, it still works.\n- **Credentials stay local.** Your access token lives in your MCP client config (or `.env` if running from source). It never leaves your machine except to authenticate with Shopify.\n- **Query results flow to your LLM.** Tool responses return to your MCP client and are passed to whichever LLM provider you've configured (Anthropic, OpenAI, etc.), so the data you query becomes visible to that provider under their terms. This is inherent to how MCP works, not specific to this server.\n- **Open source, MIT-licensed.** Auditable at [`src/shopify_partner_agent/`](src/shopify_partner_agent/).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frushikeshmore%2Fshopify-partner-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frushikeshmore%2Fshopify-partner-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frushikeshmore%2Fshopify-partner-agent/lists"}