# Medusa MCP

> Medusa (Headless E-commerce Engine) MCP connects your AI agent directly to your MedusaJS store backend. Use it to manage the full lifecycle of commerce data: list products, track specific orders, capture payments, and audit customer records without opening a dashboard. It lets you query deep inventory details, check regional tax settings, or retrieve customer profiles instantly via natural conversation.

## Overview
- **Category:** loved-by-devs
- **Price:** Free
- **Tags:** headless-commerce, order-management, product-catalog, payment-capture, inventory-tracking, customer-management

## Description

Your AI agent can now treat your entire e-commerce store like a single database accessible through plain talk. Need to know what stock levels are on the 'Classic Tee' and its variants? You just ask. Want to verify if an order is ready for shipping or check the billing address against regional tax rules? It happens instantly. This MCP lets you manage everything from product listings and collections to detailed customer profiles, giving your agent full visibility into your store’s backend operations. If you find other connectors useful, Vinkius keeps them all in one place, so connecting is simple no matter what service you need.

It's the power to talk to your commerce data. You can track recent orders, see exactly which line items belong to a purchase, and even trigger actions like capturing funds from an authorized payment method—all without ever writing a single API query.

## Tools

### capture_payment
Triggers the final capture of funds for a specific Medusa order.

### list_collections
Retrieves a list of product collections configured in your store.

### list_customers
Lists all registered customer accounts stored in the Medusa CRM directory.

### get_customer
Retrieves a specific customer's full profile data using their unique ID.

### get_order
Fetches complete details for one order, including line items and shipping/billing addresses.

### get_product
Retrieves full product information by ID, detailing its variants, options, and associated prices.

### list_orders
Lists the most recent commerce orders placed in your store.

### list_products
Lists all products available in the Medusa open-source catalog.

### list_regions
Shows configured regions, detailing their unique tax rates and supported payment providers.

### get_store_config
Retrieves general store setup data like default currencies and primary regional settings.

## Prompt Examples

**Prompt:** 
```
List all products in my Medusa store
```

**Response:** 
```
I've retrieved your product list. Highlights include the 'Classic Tee' (ID: prod-123), 'Cargo Pants' (ID: prod-456), and 'Tech Backpack' (ID: prod-789). Would you like to see the inventory levels for any of these?
```

**Prompt:** 
```
Show me the last 5 orders placed today
```

**Response:** 
```
Retrieving latest orders… I've identified 5 new orders. Highlights: Order #1001 ($45.50, Payment: Captured), Order #1002 ($120.00, Payment: Awaiting), and Order #1003 ($15.99, Status: Fulfilled). Would you like to see the shipping address for the pending order?
```

**Prompt:** 
```
Capture the payment for order ID 'order-987'
```

**Response:** 
```
Executing payment capture… Success. For order 'order-987', the funds have been captured from the customer's payment method. The order status has been updated to 'Awaiting Fulfillment' in Medusa.
```

## Capabilities

### Audit product metadata
Retrieve full details for any product ID, including pricing, inventory levels, and all available variants.

### Track order history
List recent purchases and pull detailed records covering line items, shipping addresses, payment status, and fulfillment notes.

### Process payments
Manually finalize funds transfer by triggering a capture action on an authorized customer order.

### Manage customers
Query the internal directory of registered users, retrieving full profiles and default shipping information.

### Audit store settings
Examine localized configurations like tax rates, supported currencies, and enabled payment providers across different regions.

## Use Cases

### Investigating a delayed shipment
A customer service representative asks the agent: 'What is the fulfillment status for order #9001?' The agent runs get_order, pulls up the shipping address, and confirms whether the payment was captured or if it's still awaiting processing.

### Auditing a regional sales mismatch
A finance manager needs to know which tax rules apply. They ask the agent about store configuration, triggering list_regions. The agent can then compare local taxes and payment providers across different geographies.

### Verifying product data during a bug fix
A developer suspects a price mismatch on a specific item. They use the agent to get_product by ID, instantly retrieving all details, including variants and options, for rapid debugging in their IDE.

### Completing a high-value sale
An administrator has confirmed an order is ready to ship but payment is pending. They use the agent to trigger capture_payment on the order ID, moving funds immediately and updating the status in Medusa.

## Benefits

- Instead of opening the dashboard to check inventory, you simply ask for product metadata. This lets your agent list products and get full variant details instantly, speeding up debugging time dramatically.
- You can monitor payment status without manually exporting CSV files. Simply asking for recent commerce orders gives you line-item specifics, fulfillment history, and current payment states in one go.
- Need to finalize a sale? Use the capability that triggers manual capture actions on authorized orders. This moves funds from the customer vault directly into your processing pipeline when you need it.
- Customer data is centralized. You can retrieve detailed profiles or check default shipping addresses for any registered user without navigating through multiple CRM tabs.
- Understand global sales complexity by listing store regions. You immediately know which tax rates, currencies, and payment providers are active in different markets.

## How It Works

The bottom line is you talk to your backend system using natural language, not code.

1. Subscribe to this MCP on Vinkius and input your specific Medusa Store URL and Admin API Token.
2. Your AI client authenticates the connection, granting it read/write access only for defined commerce tools.
3. You ask your agent a question (e.g., 'What is the payment status of order 123?') and get an immediate answer based on live data.

## Frequently Asked Questions

**How do I list all my products using the Medusa (Headless E-commerce Engine) MCP?**
You use the list_products tool. This retrieves a complete catalog of every product in your store, allowing you to see general availability and names for quick reference.

**Can I check payment status using the Medusa (Headless E-commerce Engine) MCP?**
Yes, use get_order. This tool retrieves full order details, including the current payment status—whether it's pending, captured, or failed.

**What is the difference between list_customers and get_customer in Medusa (Headless E-commerce Engine) MCP?**
list_customers gives you a directory of all registered users. Use get_customer when you have an ID and need to retrieve that specific person's detailed profile.

**Does the Medusa (Headless E-commerce Engine) MCP help with tax rates?**
Yes, list_regions allows you to view configured store regions. You can see localized data like active tax rates and supported payment providers for different geographies.

**Can I run payments using the Medusa (Headless E-commerce Engine) MCP?**
Yes, use capture_payment. This tool is designed to execute manual fund captures on an already authorized order ID in your store's processing pipeline.