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.

🌍 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.