# medusa-mcp

MCP server for the Medusa v2 Admin API – orders, payments, returns, products, catalog, inventory, promotions, price lists and sales reports. stdio or remote (Streamable HTTP + OAuth 2.1).

- **Type:** MCP server
- **Trust:** 85/100 (A), scored on the package rubric
- **Verification:** verified (build provenance)
- **Version:** 0.3.0
- **Author:** Pavel Trhoň
- **License:** MIT
- **npm:** medusa-mcp
- **Source:** https://github.com/trhonpavel/medusa-mcp
- **Compatible clients:** claude-code, cursor, copilot, gemini (basis: transport)

## Trust

85/100 (A), scored on the package rubric
- Publisher verified: no
- Build provenance: verified attestation
- npm trusted publishing (OIDC): yes
- Install scripts: nothing suspicious found
- Prompt-injection scan: not run
- Obfuscation scan: not run
- Evidence age: 0 days

## Security scan

- **Status:** clean
- **Scanned:** 2026-10-04T23:05:02.592Z
- **Version scanned:** 0.3.0
- **CVEs:** none found by OSV at scan time

## Tools

40 declared. Statically extracted from the shipped source — a floor on the surface, not a census.
- `list_catalog` — Product categories (with parent, so the tree can be rebuilt), collections, tags and product types – with IDs for other tools.
- `save_category` — Without category_id creates a product category (name required); with category_id updates only the given fields.
- `delete_category` — DELETES a product category (products stay, they just lose the category). Confirm with the user first.
- `save_collection` — Without collection_id creates a collection (title required); with collection_id updates it. Can add or remove products
- `delete_collection` — DELETES a collection (products stay, they just leave the collection). Confirm with the user first.
- `list_customers` — Searches customers by name, email or company, optionally within a customer group.
- `get_customer` — Customer detail with addresses, groups and order history (count, total spent, recent orders).
- `list_customer_groups` — Customer groups (e.g. B2B, VIP) – used by price lists and promotions.
- `save_customer` — Without customer_id creates a customer (email required); with customer_id updates only the given fields.
- `save_customer_group` — Without group_id creates a group (name required); with group_id renames it. Can add/remove customers.
- `delete_customer_group` — DELETES a customer group (the customers stay). Price lists and promotions targeting it stop applying. Confirm with the user first.
- `list_inventory` — Inventory items with stock per location (stocked, reserved, available). With low_stock_threshold returns only items at or below the threshold.
- `set_stock_level` — Sets the stocked quantity of an item at a location. Provide either an absolute 'stocked_quantity' or a relative 'adjust_by' (+/-).
- `list_orders` — Lists orders, newest first. Filters: full-text, date range (YYYY-MM-DD in the reporting timezone), customer, order/payment/fulfillment status.
- `get_order` — Full order detail – line items, addresses, payments (with captures and refunds), fulfillments, tracking numbers and returns.
- `create_fulfillment` — Creates a fulfillment for an order. Without 'items' it fulfills all remaining unfulfilled quantities.
- `create_shipment` — Marks a fulfillment as shipped and attaches a tracking number. Without 'fulfillment_id' it uses the only unshipped fulfillment.
- `mark_delivered` — Marks a fulfillment as delivered. Without 'fulfillment_id' it uses the only fulfillment that is not delivered yet.
- `cancel_fulfillment` — Cancels a fulfillment that has not been shipped yet, so its items can be fulfilled again.
- `complete_order` — Marks the order as completed.
- `cancel_order` — CANCELS the order. Irreversible – get explicit confirmation from the user before calling. The order must not have active fulfillments.
- `update_order` — Changes the order's email, shipping or billing address, or metadata (e.g. an internal note). Send only what should change;
- `mark_order_paid` — Records a manual payment (e.g. a received bank transfer or cash on delivery) for the order's unpaid payment collection.
- `capture_payment` — Captures an authorized payment (charges the customer). Without 'amount' captures the full remaining amount.
- `refund_payment` — REFUNDS money to the customer through the payment provider. Irreversible – confirm the amount with the user before calling.
- `create_return` — Requests a return of order items (the customer is sending them back). Without 'items' returns every shipped item.
- `receive_return` — Records that returned items arrived; they go back to stock. Without 'items' receives everything requested.
- `create_draft_order` — Creates a draft order on behalf of a customer (phone or e-mail orders, B2B). Items by variant_id or SKU (of published products), optionally with a custom unit p
- `convert_draft_order` — Turns a draft order into a regular order (reserves stock). Record the payment afterwards with mark_order_paid.
- `list_price_lists` — Price lists – sales (temporary discounted prices) and overrides (e.g. B2B prices for a customer group).
- `save_price_list` — Without price_list_id creates a price list (title required); with price_list_id updates it.
- `delete_price_list` — DELETES a price list – its prices stop applying immediately. Confirm with the user first.
- `list_products` — Lists products with their variants (SKUs). Filter by full-text, status, collection, category or tag.
- `get_product` — Product detail – variants, prices in all currencies, linked inventory items, options, categories, collection, tags, images and sales channels.
- `create_product` — Creates a product with its variants and prices. For a simple product without options pass just 'prices' (and optionally 'sku', 'stock').
- `update_product` — Updates product fields – texts, status, handle, images, collection, categories, tags, sales channels, metadata.
- `delete_product` — DELETES the product with all its variants. Irreversible – get explicit confirmation from the user before calling.
- `create_variant` — Adds a variant to an existing product, e.g. a new size. 'options' must name every product option; new option values are added automatically.
- `update_variant` — Updates variant fields – title, SKU, barcodes, inventory tracking, backorders, weight, metadata. For prices use set_variant_price.
- `delete_variant` — DELETES one variant of a product. Irreversible – confirm with the user first. 'confirm' must equal the variant's SKU (or its title when it has no SKU).

## Install

**Verdict: install** — No blocking findings and no open coverage gaps — safe to install as configured.
**Config** (claude-code):
```json
"{\n  \"mcpServers\": {\n    \"medusa\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"medusa-mcp\"\n      ],\n      \"env\": {\n        \"MEDUSA_API_KEY\": \"<YOUR_MEDUSA_API_KEY>\"\n      }\n    }\n  }\n}"
```
**Credentials it will ask for** (names only — Forge never holds a value):
- `MEDUSA_API_KEY` — Medusa API Key (required)
Placeholders only. Forge never holds, brokers, or transmits a credential value — replace each <YOUR_NAME> in your own config file. Do not send a value back to Forge; no Forge endpoint accepts one.
- This entry needs 1 credential (1 required). The generated config carries placeholders, so it will fail in the editor rather than at runtime if they are left unset.

## Blast radius

Extensive blast radius — deletes data; holds an api key.
- Floor 57, ceiling 57 (tier: extensive)
- This is impact, not likelihood. A high radius is not a defect: a filesystem server is supposed to write files. It is never part of the trust score.

## Machine-readable views of this entry

- Signed JSON: https://forgeregistry.com/api/v1/packages/medusa-mcp
- Install plan: https://forgeregistry.com/api/v1/packages/medusa-mcp/install-plan
- Alternatives: https://forgeregistry.com/api/v1/alternatives/medusa-mcp
- HTML page: https://forgeregistry.com/registry/medusa-mcp
- MCP: POST https://forgeregistry.com/api/mcp → `forge_get_package` / `forge_install_plan`

## About this document

Generated by Forge (https://forgeregistry.com) — a compact rendering of the same record served, signed, at the JSON URL above. Trust and scan facts are the registry's own measurements; anything Forge did not measure is named as unmeasured rather than omitted.