EasyCRM MCP

EasyCRM MCP

An MCP server for one Shopify store and one Horoshop store. Tools are grouped by platform and resource so each action has a clear destination and input contract.

The server runs locally and sends requests directly to each configured platform. Credentials stay in your MCP client configuration on your machine.

Quick start

https://github.com/user-attachments/assets/ab10078a-c557-4f72-b37a-1958c3991029

npx -y easycrm-mcp init

To run the setup wizard directly from a repository checkout, use npm ci and npm run dev -- init.

The wizard lets you configure Shopify, Horoshop, or both. It verifies each connection and registers the server in the client you pick:

• Claude Code
• Codex CLI
• Gemini CLI
• Claude Desktop
• Cursor
• Windsurf
• VS Code (Copilot)

Pick "Other" to print a config entry for any other MCP client.

Store credentials

Shopify

You need a store on a plan with Admin API access and one of:

Option A: Dev Dashboard app (for stores in your own Shopify organization)

1. Go to dev.shopify.com/dashboard and create an app for a store in your organization. Shopify limits client credentials to stores in your own organization.

2. Grant only the scopes needed for the tools you plan to use:

   Resource	Read	Write
   Themes	read_themes	write_themes
   Shopify Files for theme media	read_files	write_files
   Pages	read_content	write_content
   Menus	read_online_store_navigation	write_online_store_navigation
   Products and variants	read_products	write_products
   Inventory	read_inventory, read_locations	write_inventory
   Customers	read_customers	write_customers
   Orders	read_orders	write_orders
   Fulfillment orders	Matching assigned, merchant-managed, or third-party fulfillment read scope	Matching fulfillment write scope
   Discounts	read_discounts	write_discounts
   Native sales reports	read_reports	None

   Shopify customer data also requires protected customer data approval. Orders older than 60 days normally require read_all_orders. Some actions require additional staff permissions or an offline token. The individual tool descriptions state these cases.The native Shopify sales report requires Level 2 protected customer data access, as documented for shopifyqlQuery.

3. Copy the Client ID and Client Secret from the app's settings.

Option B: existing admin access token

Use an existing shpat_… token from an admin-created custom app. Shopify no longer allows creating new admin-created custom apps.

Editing theme files requires Shopify's write_themes exemption in addition to the API scope. See Shopify's themeFilesUpsert requirements.

Horoshop

Create a dedicated API admin login in the Horoshop admin panel under Settings > Admins. Configure the store's HTTPS origin, login, and password. Horoshop issues an API token valid for 600 seconds; this server renews it automatically. See the official Horoshop API documentation and authentication details.

Manual configuration

If you skip the wizard, add this to your MCP client's config:

{
  "easycrm": {
    "command": "npx",
    "args": ["-y", "easycrm-mcp"],
    "env": {
      "SHOPIFY_STORE_DOMAIN": "your-store.myshopify.com",
      "SHOPIFY_CLIENT_ID": "…",
      "SHOPIFY_CLIENT_SECRET": "…",
      "HOROSHOP_STORE_URL": "https://shop.example.com",
      "HOROSHOP_LOGIN": "your_api_login",
      "HOROSHOP_PASSWORD": "…"
    }
  }
}

You can configure either platform by omitting the other platform's variables. For Shopify, you can use an existing access token instead of client credentials by setting SHOPIFY_ADMIN_ACCESS_TOKEN.

Tools

Shopify

Horoshop

Each tool is tied to one configured platform. Horoshop product creation accepts image URLs for a variant gallery or a shared gallery. Image updates require an explicit append or replace mode; replace removes the existing images in that gallery. Horoshop fetches images from the supplied URLs, with a 5 MB limit for each source image. The product list supports offset and limit for paging, with a maximum of 500 products per request per the Horoshop export API. Horoshop category export requires platform version 4 or later.

horoshop_product_reviews accepts a product URL or path on the configured store. It reads public schema.org/Review markup, including reviews without star ratings. It tries a plain HTTP request first. For a JavaScript challenge or additional review batches, it opens a temporary headless Chrome session and closes it after the read. Chrome must be installed locally; no browser is downloaded with this package. Set HOROSHOP_BROWSER_EXECUTABLE_PATH if Chrome is installed in a nonstandard location. maxReviews defaults to 20 and is capped at 100. totalCount reflects the page's review count, and complete: false means more reviews may exist. The tool does not read private or unpublished reviews.

Before editing theme files, call shopify_theme_active or shopify_theme_list. The update tool checks the observed role again. Editing the live MAIN theme requires explicit user approval and confirmLiveTheme: true; publishing requires approval, confirmPublish: true, and the expected current MAIN theme ID. Draft themes can be edited without changing the live storefront. Shopify requires a theme API exemption for theme mutations.

To change a theme banner image or video, inspect its settings with shopify_theme_media_slots using the relevant template path, for example templates/index.json. The result identifies section, block, and setting IDs, including empty media pickers. Upload a local file with shopify_theme_media_upload_local, wait for shopify_theme_media_file_status to report READY, then call shopify_theme_media_set with the returned file ID and the slot's observed value. The setter checks the theme schema and current value again, and changes only that setting. Images may be PNG, JPEG, WebP, or GIF up to 20 MB. Video upload currently supports MP4 up to 1 GB and streams the local file. The file path is read on the machine running the MCP server. video_url settings for YouTube or Vimeo are separate from Shopify-hosted video pickers and are not handled by this flow. A concurrent Theme Editor save during the final theme file write can still overwrite changes because Shopify does not offer an atomic compare-and-swap for theme JSON files.

Shopify product images can be submitted from public HTTPS URLs or local files. The local-image tool accepts an absolute path on the MCP server machine and uploads one PNG, JPEG, WebP, or GIF up to 20 MB through Shopify staging before attaching it to the product. Shopify processes images asynchronously, so use shopify_product_media_list to check readiness. Creating a draft with an initial price uses a second mutation for the default variant. If that step fails, the tool returns the created product ID and marks the partial result as an error.

Analytics

• shopify_sales_report reads native Shopify Analytics through ShopifyQL. Select a date range, total/daily/monthly interval, and metrics such as sales, orders, discounts, and average order value. This requires read_reports and Level 2 protected customer data access.
• shopify_order_summary calculates order counts and current order totals from accessible orders. It reports paginationComplete and a cursor when it stops before the last page.
• horoshop_order_summary calculates order counts, paid counts, totals by currency, and breakdowns by status and UTM source from the Horoshop orders API. Currency totals are exact decimal strings, for example "0.3". It scans at most 5,000 orders and reports complete: false if more may exist.

The two order summaries are calculated from API orders, not native analytics reports or settled payment revenue. Horoshop total_sum includes discounts and excludes shipping. The server does not currently expose traffic, sessions, or conversion funnel analytics for Horoshop.

Purchase history

Both purchase history tools read store data through the configured API connection. Shopify searches orders by customer ID, newest first, and returns an order cursor for the next page. Each order includes up to 20 line items; when itemsComplete is false, pass nextItemsCursor and the order ID to shopify_order_line_items to read more. Shopify normally limits order access to the most recent 60 days unless the app has read_all_orders.

Horoshop has no documented customer filter for orders/get, so horoshop_customer_purchase_history scans up to maxPages pages of 100 orders, matching delivery_email exactly without regard to letter case. Use from and to to narrow the search. If complete is false, pass nextOffset as offset in another call to continue. An empty result with complete: false does not establish that the customer has no earlier purchases.

The current tools do not cover every action in either admin. In particular, Shopify refunds, partial fulfillment, edits to line items, advanced discount types, and Horoshop customer deletion or order creation/deletion need separate workflows and API verification. Shopify cancellation returns a job ID because processing is asynchronous. See the architecture notes for the extension plan.

Moving from the Shopify-only package

The previously published shopify-store-builder-mcp package remains available. To use this package, replace the npm command with easycrm-mcp, use the new easycrm MCP entry, and update tool names to their shopify_ versions. Horoshop variables can then be added to the same entry.

Development

npm install
npm run dev     # run from source
npm run build   # compile to dist/
npm test
npm audit

License

ISC