Medusa

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.