medusa-mcp

Overview

medusa-mcp is a Model Context Protocol (MCP) server designed for integration with the Medusa JavaScript SDK. It provides a scalable backend layer for managing and interacting with Medusa’s data models, enabling automation, orchestration, and intelligent service extensions.

---

🧩 What is an MCP Server?

An MCP server is a modular, extensible backend that:

• Enables real-time service orchestration
• Supports standardized, high-throughput communication
• Acts as a bridge between AI/automation tools and real-world systems

These servers are used in areas like AI, IoT, and enterprise software to connect various services and automate tasks using standardized protocols like JSON-RPC.

🔑 Key Features

• Modular Architecture – Composable services for flexibility
• High Efficiency – Optimized for speed and scale
• Extensible Design – Add new capabilities easily
• Cross-Environment Deployment – Cloud, on-prem, or hybrid
• AI-Ready Interfaces – Integrate LLMs and tools seamlessly

🧠 Role in AI Systems

MCP servers allow AI agents to:

• Access real-time data from APIs, files, or databases
• Automate business processes (e.g., order fulfillment, pricing updates)
• Interact with external services in a secure and controlled way

---

---

🚀 Medusa JS + MCP

Using medusa-mcp, Medusa JS can:

• Automate workflows (e.g., inventory or pricing adjustments)
• Connect with external tools (email, analytics, etc.)
• Use AI agents to analyze trends and trigger actions
• Enable scalable, modular architecture for commerce platforms

---

✨ Features

• ✅ Model Context Protocol (MCP) support
• 📈 Scalable infrastructure
• 🧱 Extensible plugin architecture
• 🔗 Integrated with Medusa JS SDK

---

🛠️ Installation

Clone the repository and install dependencies:

npm install

Build the project:

npm run build

---

▶️ Usage

Start the server:

npm start

Test using the MCP Inspector:

npx @modelcontextprotocol/inspector ./dist/index.js

Note: Restart the Inspector and your browser after each rebuild.

---

🛠️ Generating a Claude Skill from this MCP server

You can convert this MCP server into a Claude Skill using the mcp-to-skill.py script from the mcp-to-skill-converter project, which is included in this repo as mcp-to-skill.py.

1. Build the MCP server (so the command in the config works):

   npm run build

2. Ensure Python and the mcp package are available:

   pip install mcp

3. Generate a Skill for this server using the provided mcp-to-skill.json config:

   python mcp-to-skill.py --mcp-config mcp-to-skill.json --output-dir ./skills/medusa-mcp

   This will create:

   • SKILL.md – instructions for Claude
   • executor.py – MCP communication handler
   • mcp-config.json – MCP server configuration
   • package.json – minimal dependencies for the skill

4. Install the Skill for Claude:

   cd skills/medusa-mcp
   pip install mcp
   cp -r . ~/.claude/skills/medusa-mcp

Claude will automatically discover the new Skill on next startup.

---

🌍 Environment Variables

Variable	Description
MEDUSA_BACKEND_URL	Your Medusa backend URL
PUBLISHABLE_KEY	Your Medusa publishable API key
MEDUSA_USERNAME	Medusa admin username (for admin)
MEDUSA_PASSWORD	Medusa admin password (for admin)

Server runs at: http://localhost:3000

---

🧠 Architecture Diagram

Here's how the medusa-mcp server fits into a typical setup with Medusa JS and external systems:

       +-------------------------+
       |     AI Assistant /      |
       |     LLM / Automation    |
       +-----------+-------------+
                   |
                   v
    +--------------+--------------+
    |     MCP Server (medusa-mcp) |
    |-----------------------------|
    | - JSON-RPC Communication    |
    | - AI-Ready Interface        |
    | - Plugin Support            |
    +------+----------------------+
                   |                             
                   +
                   |                                                         
                   v                                                         
         +-------------------+
         | Medusa Backend    |
         | (Products, Orders)|
         +-------------------+
                   |
                   |
                   v
           +--------------+
           | Medusa Store |
           | Frontend     |
           +--------------+
                   |
                   |
                   v
      +-------------------------+
      | External Services / API |
      | (e.g., Payments, Email) |
      +-------------------------+

🧪 Customization

To tailor the server to your Medusa setup:

Replace admin.json and store.json with your own OAS definitions for fine-grained control.

• Replace the OpenAPI schemas in the oas/ folder:
  • admin.json – Admin endpoints
  • store.json – Storefront endpoints

Use the @medusajs/medusa-oas-cli to regenerate these files.

You can also fork this project to build your own custom MCP-powered Medusa integration.

---

🤝 Contributing

We welcome contributions! Please see our CONTRIBUTING.md guide.

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.