Medusa README

medusa-mcp

🇨🇿 Česky

An MCP server for the Medusa v2 Admin API. It lets Claude, ChatGPT or any MCP client run a Medusa store: orders, payments and refunds, returns, order edits, draft orders, products and catalog, inventory, customers, promotions and price lists – plus sales, customer and restock analytics with interactive dashboards right in the chat.

• 55 tools for day-to-day store management, and medusa_request for any other Admin API endpoint
• Interactive views (MCP Apps) – a sales dashboard and a restock planner render inline in Claude and ChatGPT
• Prompts – ready-made workflows (store briefing, fulfillment, returns, restocking, monthly report…) as slash commands
• Resources – orders, products and customers as attachable context, with autocompletion
• Guard rails – previews (dry run) for bulk changes, confirmation dialogs for destructive actions, an audit log of every change

It runs in two modes:

• stdio – locally for Claude Desktop, Claude Code and other MCP clients
• Streamable HTTP + OAuth 2.1 – as a remote connector for Claude (web, desktop, mobile) and ChatGPT

It is listed in the MCP Registry as io.github.trhonpavel/medusa-mcp, and also ships as a Claude Code / Cowork plugin with skills and as a one-click Claude Desktop extension (.mcpb).

Tools

Read and analyze

Write (not registered with MEDUSA_READ_ONLY=true)

Generic

Amounts are in major currency units (Medusa v2 does not store minor units). Plain dates (2026-09-01) are interpreted in REPORT_TIMEZONE (default UTC). Large reports send MCP progress notifications.

Fewer tools, less context: MEDUSA_TOOLSETS=orders,reports registers only those groups (orders, customers, products, catalog, inventory, pricing, promotions, reports, bulk, raw; get_store_info is always on).

Beyond tools

Interactive views (MCP Apps). sales_report and inventory_forecast come with HTML views that clients supporting MCP Apps – Claude, ChatGPT, VS Code, Goose – render inline: KPI tiles with period-over-period changes, a revenue chart, top products, discount codes and countries; and a sortable restock table with status filters, adjustable lead time and a button that asks the assistant to draft a purchase order. The views follow the client's theme and language (Czech or English), switch periods by calling the tools themselves, and make no network requests of their own. Other clients get the same data as text.

Prompts. store_briefing, fulfill_orders, restock_plan, handle_return, customer_overview, monthly_report and plan_promotion – each walks the assistant through a whole workflow and asks before changing anything. Arguments autocomplete (order numbers, customer e-mails, months).

Resources. medusa://store, medusa://orders/{order}, medusa://products/{handle} and medusa://customers/{email} – attach an order or a product to the conversation (e.g. with @ in Claude Code); recent orders are listed and every template autocompletes.

Confirmations. Destructive actions – canceling, refunding, capturing, deleting, bulk changes and writes through medusa_request – ask the user directly through MCP elicitation with a plain-language summary ("Refund 249 CZK to the customer of order 1042?") when the client supports it (Claude Code). A declined dialog changes nothing. Turn it off with MEDUSA_CONFIRM_DESTRUCTIVE=false. The stateless remote connector cannot elicit, so there the client's own tool approval applies.

1. Create a Medusa API key

In the Medusa Admin go to Settings → Developer → Secret API Keys → Create. The key (sk_…) acts with the permissions of the user who created it, so consider a dedicated admin user that you can revoke independently.

2. Local use (stdio)

Claude Code / Cowork plugin

claude plugin marketplace add trhonpavel/medusa-mcp
claude plugin install medusa@medusa-mcp

Claude Code asks for the backend URL and the API key when you enable the plugin (the key goes to the system keychain). Write tools stay off until you turn off Read-only in /config. Besides the server's prompts, the plugin adds two skills:

• store-briefing – sales vs the previous period, paid orders waiting to ship, what to restock
• fulfill-orders – fulfill paid orders and add tracking numbers, after you confirm the list

Claude Desktop extension

Download medusa-mcp-<version>.mcpb from the latest release and open it, or drag it to Settings → Extensions. Claude Desktop asks for the same settings and runs the server with its bundled Node.js. Build it yourself with npm run build:mcpb.

Manual configuration

Claude Desktop – claude_desktop_config.json:

{
  "mcpServers": {
    "medusa": {
      "command": "npx",
      "args": ["-y", "medusa-mcp", "stdio"],
      "env": {
        "MEDUSA_BACKEND_URL": "https://api.example.com",
        "MEDUSA_API_KEY": "sk_...",
        "MEDUSA_READ_ONLY": "true"
      }
    }
  }
}

Claude Code:

claude mcp add medusa \
  -e MEDUSA_BACKEND_URL=https://api.example.com -e MEDUSA_API_KEY=sk_... \
  -- npx -y medusa-mcp stdio

3. Remote connector (HTTP + OAuth)

docker run -d --name medusa-mcp -p 127.0.0.1:3000:3000 -v medusa-mcp-data:/data \
  -e MEDUSA_BACKEND_URL=https://api.example.com \
  -e MEDUSA_API_KEY=sk_... \
  -e PUBLIC_URL=https://mcp.example.com \
  -e OWNER_PASSWORD="$(openssl rand -base64 24)" \
  ghcr.io/trhonpavel/medusa-mcp:latest

Or clone the repo, copy .env.example to .env and run docker compose up -d --build.

The server listens on 127.0.0.1:3000; expose it through a reverse proxy with TLS. Claude connects to remote connectors from Anthropic's servers, so the endpoint must be publicly reachable over HTTPS. Caddy example:

mcp.example.com {
    reverse_proxy 127.0.0.1:3000
}

Then add a custom connector in Claude with the URL https://mcp.example.com/mcp. Claude registers itself (Dynamic Client Registration), opens the consent page, you enter OWNER_PASSWORD and click Allow.

ChatGPT

In ChatGPT turn on developer mode in the settings, then create an app (connector) with the MCP server URL https://mcp.example.com/mcp and OAuth authentication. ChatGPT registers itself the same way and redirects to chatgpt.com, which is in the default ALLOWED_REDIRECT_HOSTS. The server returns the RFC 9207 iss parameter, so ChatGPT uses its stable callback URL.

Claude Code

Claude Code can use the same OAuth flow, or a static token if you set MCP_STATIC_TOKEN:

claude mcp add --transport http medusa https://mcp.example.com/mcp \
  --header "Authorization: Bearer <MCP_STATIC_TOKEN>"

Configuration

Endpoints

Security model

• The Medusa API key never leaves the server. Clients get their own short-lived tokens (1 h access, 30-day refresh with rotation).
• Only SHA-256 hashes of tokens are stored, in DATA_DIR/oauth-state.json (mode 600). Delete the file to sign out every client.
• Dynamic Client Registration only accepts redirect URIs on ALLOWED_REDIRECT_HOSTS, so an arbitrary app cannot register its own callback and phish a token.
• Authorization codes are single-use, expire after 5 minutes, and PKCE S256 is mandatory.
• The consent page sends Content-Security-Policy: default-src 'none' and X-Frame-Options: DENY, and compares the password in constant time.
• Write tools are not marked readOnlyHint, and tools that cancel, delete or move money carry destructiveHint, so clients like Claude ask for approval before running them.
• medusa_request only reaches /admin/… paths, never writes to api-keys, users or invites (so a prompt injection cannot mint new credentials), and can be disabled with MEDUSA_RAW_API=false.
• Every write tool call is logged as [audit] {…} on stderr (docker logs) – time, tool, OAuth client (e.g. "Claude"), outcome and arguments – and to AUDIT_LOG when set.
• Destructive actions ask for confirmation through MCP elicitation when the client supports it; bulk tools and edit_order preview by default and change nothing until called with dry_run: false.
• add_product_images downloads only from public http(s) addresses: private, loopback and link-local targets are refused, also after redirects, so the server cannot be used to reach its own network.
• The interactive views are self-contained HTML (no external scripts or requests) and are rendered by the client in a sandboxed iframe.
• Set TRUST_PROXY to the number of reverse proxies in front of the server, otherwise rate limiting only sees the proxy's IP.

See SECURITY.md for reporting vulnerabilities.

Development

npm ci
npm run build   # TypeScript + the MCP Apps views (dist/apps/*.html with the ext-apps runtime inlined)
npm test        # build + tests against a mock Medusa (tools, prompts, resources, views and the full OAuth flow)
npm run smoke   # read-only check against a real Medusa – prints response shapes only, no data
npm run dev     # HTTP mode via tsx

npm run smoke needs MEDUSA_BACKEND_URL and MEDUSA_API_KEY. Its output contains only keys and types, so it is safe to paste into an issue.

License

MIT