Medusa MCP server

medusa-mcp

🇨🇿 Česky

An MCP server for the Medusa v2 Admin API. It gives Claude (or any MCP client) access to orders, customers, products and inventory, computes sales reports, and performs a small set of carefully scoped write actions.

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

Amounts are in major currency units (Medusa v2 does not store minor units). Plain dates in filters (2026-09-01) are interpreted in REPORTTIMEZONE (default UTC). With MEDUSAREAD_ONLY=true the write tools are not registered at all.

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. The plugin adds two skills:

• store-briefing – yesterday's and month-to-date sales, paid orders waiting to ship, low stock
• fulfill-orders – fulfill paid orders and add tracking numbers, after you confirm the list

Claude Desktop extension

Download medusa-mcp-.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 – claudedesktopconfig.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:

Shortened. The full README is on GitHub.