# Medusa [Health: Active]

**Category:** 🛒 E-Commerce  
**Repository:** https://github.com/trhonpavel/medusa-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1272  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/medusa

## Description
Medusa v2 store: orders, customers, products, inventory, sales reports and safe write actions.

## Tools
Capabilities this server exposes over MCP:

- **get_store_info** — regions and currencies, sales channels, stock locations, shipping options and profiles, return and refund reasons
- **list_orders** — orders by full-text, date range, customer or status; full detail by ID or order number (`1042`) with payments, refunds, discount codes and returns
- **list_customers** — customers (also by group or e-mail), order history, total spent
- **list_customer_groups** — customer groups
- **list_products** — products by status, collection, category or tag; variants, options, prices, images, inventory items (by ID or handle)
- **list_catalog** — categories (tree), collections, tags, product types
- **list_inventory** — stock per location, `low_stock_threshold` to find what's running out
- **list_promotions** — discount codes with conditions, usage and validity; sale and customer-group price lists
- **sales_report** — revenue, net revenue after refunds, AOV, units, customers – **compared with the previous period or last year**, day/week/month series, top products and variants, countries, discount codes, sales channels · *interactive dashboard*
- **customer_report** — new vs returning customers, repeat purchase rate, top customers, lapsed customers worth winning back
- **inventory_forecast** — sales velocity vs stock: days of cover, out-of-stock / reorder-now / reorder-soon, suggested order quantities, slow movers · *interactive restock planner*
- **medusa_request** — any Admin API endpoint (`GET`, `POST`, `DELETE` under `/admin/`) for things without a dedicated tool – reservations, exchanges, tax rates… Read-only mode allows `GET` only; writes to `api-keys`, `users` and `invites` are always blocked. Turn it off with `MEDUSA_RAW_API=false`.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "medusa": {
    "command": "npx",
    "args": ["-y","medusa-mcp"],
    "env": {
      "MEDUSA_READ_ONLY": "",
      "MEDUSA_RAW_API": "",
      "MEDUSA_TOOLSETS": "",
      "REPORT_TIMEZONE": "",
      "MEDUSA_CONFIRM_DESTRUCTIVE": ""
    }
  }
}
```

**Requires environment variables:** `MEDUSA_READ_ONLY`, `MEDUSA_RAW_API`, `MEDUSA_TOOLSETS`, `REPORT_TIMEZONE`, `MEDUSA_CONFIRM_DESTRUCTIVE` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Medusa does

The Medusa MCP server exposes Medusa v2 store administration through MCP. It covers common commerce data and actions, including orders, payments, refunds, returns, fulfillment, draft orders, products, variants, catalog structures, inventory, customers, promotions, and price lists.

Read-oriented tools can filter orders by text, dates, customer, or status; inspect customer history and spending; find products by catalog attributes; check stock by location; and examine promotion conditions and usage. Reporting tools compare sales with a previous period or the same period last year, while customer reporting separates new and returning buyers and identifies lapsed customers. Inventory forecasting combines sales velocity with current stock to estimate days of cover and suggested replenishment quantities.

This fits the 🛒 E-Commerce category for teams that want an assistant to inspect or operate a Medusa store without building a separate integration for every supported workflow.

## How it works

The Medusa MCP server can run locally over stdio or remotely over Streamable HTTP with OAuth 2.1. Local use is intended for clients such as Claude Desktop and Claude Code. The remote connector is documented for Claude and ChatGPT environments. The server authenticates against a Medusa Admin API using a secret API key created in Medusa Admin; that key inherits the permissions of its creating user.

In addition to tools, the server supplies workflow prompts for activities such as store briefings, fulfillment, returns, restocking, customer overviews, monthly reports, and promotion planning. Resources expose the store, orders, products, and customers as attachable context. Clients that support MCP Apps can render inline sales and restocking views; other clients receive the same underlying data as text.

## Setup and configuration

Create a secret API key in Medusa Admin under Settings, Developer, and Secret API Keys. The repository documents a Claude Code or Cowork plugin, a downloadable Claude Desktop extension, and manual local configuration. The plugin asks for the backend URL and API key during activation, while the extension asks for equivalent settings.

Write operations are disabled when `MEDUSA_READ_ONLY=true`. `MEDUSA_RAW_API=false` disables the generic raw Admin API request tool. `MEDUSA_TOOLSETS` can limit registration to groups such as orders, customers, products, catalog, inventory, pricing, promotions, reports, bulk, or raw; store information remains enabled. `REPORT_TIMEZONE` controls interpretation of plain report dates and defaults to UTC. `MEDUSA_CONFIRM_DESTRUCTIVE=false` disables confirmation dialogs for destructive actions.

## Tools and capabilities

The dedicated tools include:

- Store information, orders, customers, customer groups, products, catalog data, inventory, promotions, and price lists.
- Sales, customer, and inventory forecast reports, with interactive dashboards where the client supports MCP Apps.
- Fulfillment, shipment, order, payment, return, draft-order, product, variant, catalog, inventory, customer, promotion, and price-list changes.
- Bulk price, stock, and product updates that preview changes through a dry-run option.
- `medusa_request` for supported `GET`, `POST`, and `DELETE` requests under `/admin/` when no dedicated tool exists.

Destructive operations can request confirmation through MCP elicitation when the client supports it. The raw request tool always blocks writes to `api-keys`, `users`, and `invites`; read-only mode also restricts it to `GET` requests.

## Limitations and notes

The server acts on the permissions of the configured Medusa Admin API key, so access depends on the user who created that key. Write tools are not available while read-only mode is enabled. The stateless remote connector cannot use elicitation dialogs, so approval is handled by the client’s own tool-approval behavior.

Amounts use major currency units because Medusa v2 does not store minor units. The interactive views make no network requests of their own and require a client with MCP Apps support for inline rendering. Clients without that support still receive report data as text.

_Full upstream README: https://allmcps.com/mcp/medusa/readme_