# Medusa Mcp

> MCP server for Medusa JS SDK

- **Type:** MCP server
- **Install:** `agentstack add mcp-sgfgov-medusa-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SGFGOV](https://agentstack.voostack.com/s/sgfgov)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SGFGOV](https://github.com/SGFGOV)
- **Source:** https://github.com/SGFGOV/medusa-mcp

## Install

```sh
agentstack add mcp-sgfgov-medusa-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

[](https://mseep.ai/app/sgfgov-medusa-mcp)

# `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:

```bash
npm install
```

Build the project:

```bash
npm run build
```

---

## ▶️ Usage

Start the server:

```bash
npm start
```

Test using the MCP Inspector:

```bash
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](https://github.com/GBSOSS/-mcp-to-skill-converter/blob/main/mcp_to_skill.py), which is included in this repo as `mcp-to-skill.py`.

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

   ```bash
   npm run build
   ```

2. **Ensure Python and the `mcp` package are available**:

   ```bash
   pip install mcp
   ```

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

   ```bash
   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**:

   ```bash
   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](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`](https://www.npmjs.com/package/@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](CONTRIBUTING.md) guide.

---

## 📄 License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SGFGOV](https://github.com/SGFGOV)
- **Source:** [SGFGOV/medusa-mcp](https://github.com/SGFGOV/medusa-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sgfgov-medusa-mcp
- Seller: https://agentstack.voostack.com/s/sgfgov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.