Medusa MCP Server
medusa-mcp
개요
medusa-mcp 는 Medusa JavaScript SDK와 통합되도록 설계된 모델 컨텍스트 프로토콜(MCP) 서버 입니다. Medusa 데이터 모델을 관리하고 상호 작용할 수 있는 확장 가능한 백엔드 계층을 제공하여 자동화, 오케스트레이션 및 지능형 서비스 확장을 지원합니다.
Related MCP server: Example MCP SSE Server
🧩 MCP 서버란 무엇인가요?
MCP 서버는 다음과 같은 특징을 갖춘 모듈식 확장 가능 백엔드입니다.
실시간 서비스 오케스트레이션을 지원합니다.
표준화된 고처리량 통신 지원
AI/자동화 도구와 실제 시스템 간의 브리지 역할을 합니다.
이러한 서버는 AI, IoT, 엔터프라이즈 소프트웨어 분야에서 JSON-RPC와 같은 표준화된 프로토콜을 사용하여 다양한 서비스를 연결하고 작업을 자동화하는 데 사용됩니다.
🔑 주요 특징
모듈형 아키텍처 - 유연성을 위한 구성 가능한 서비스
고효율성 – 속도와 규모에 최적화됨
확장 가능한 디자인 – 새로운 기능을 쉽게 추가하세요
교차 환경 배포 - 클라우드, 온프레미스 또는 하이브리드
AI 지원 인터페이스 - LLM 및 도구를 원활하게 통합
🧠 AI 시스템의 역할
MCP 서버를 사용하면 AI 에이전트는 다음을 수행할 수 있습니다.
API, 파일 또는 데이터베이스에서 실시간 데이터에 액세스
비즈니스 프로세스 자동화(예: 주문 이행, 가격 업데이트)
안전하고 통제된 방식으로 외부 서비스와 상호 작용합니다.
🚀 메두사 JS + MCP
medusa-mcp 사용하면 Medusa JS에서 다음을 수행할 수 있습니다.
워크플로 자동화(예: 재고 또는 가격 조정)
외부 도구(이메일, 분석 등)와 연결합니다.
AI 에이전트를 사용하여 추세를 분석하고 작업을 트리거합니다.
상거래 플랫폼을 위한 확장 가능한 모듈형 아키텍처 활성화
✨ 특징
✅ 모델 컨텍스트 프로토콜(MCP) 지원
📈 확장 가능한 인프라
🧱 확장 가능한 플러그인 아키텍처
🔗 Medusa JS SDK와 통합됨
🛠️ 설치
저장소를 복제하고 종속성을 설치합니다.
지엑스피1
프로젝트를 빌드하세요:
npm run build▶️ 사용법
서버를 시작합니다:
npm startMCP Inspector를 사용하여 테스트:
npx @modelcontextprotocol/inspector ./dist/index.js참고: 다시 빌드한 후에는 Inspector와 브라우저를 다시 시작하세요.
🌍 환경 변수
변하기 쉬운 | 설명 |
| Medusa 백엔드 URL |
| Medusa 게시 가능 API 키 |
| Medusa 관리자 사용자 이름(관리자용) |
| Medusa 관리자 비밀번호(관리자용) |
서버는 http://localhost:3000 에서 실행됩니다.
🧠 아키텍처 다이어그램
Medusa JS와 외부 시스템을 갖춘 일반적인 설정에서 medusa-mcp 서버가 어떻게 적용되는지는 다음과 같습니다.
+-------------------------+
| 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) |
+-------------------------+🧪 사용자 정의
서버를 Medusa 설정에 맞게 조정하려면 다음을 수행합니다.
더욱 세부적인 제어를 위해
admin.json과store.json사용자 고유의 OAS 정의로 바꾸세요.
oas/폴더의 OpenAPI 스키마를 다음과 같이 바꾸세요.admin.json– 관리자 엔드포인트store.json– 스토어프런트 엔드포인트
@medusajs/medusa-oas-cli 사용하여 이러한 파일을 다시 생성합니다.
이 프로젝트를 포크하여 사용자 정의 MCP 기반 Medusa 통합을 구축할 수도 있습니다.
🤝 기여하기
기여를 환영합니다! CONTRIBUTING.md 가이드를 참조하세요.
📄 라이센스
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 라이선스 파일을 참조하세요.
Available Tools
48 toolsGetCartsIdC
Retrieve a cart by its ID. You can expand the cart's relations or select the fields that should be returned.
Inputs: id, fields.
GetCollectionsC
Retrieve a list of collections. The collections can be filtered by fields such as handle. The collections can also be sorted or paginated.
Inputs: fields, offset, limit, order, +7 more.
GetCollectionsIdB
Retrieve a collection by its ID. You can expand the collection's relations or select the fields that should be returned.
Inputs: id, fields.
GetCurrenciesC
Retrieve a list of currencies. The currencies can be filtered by fields such as code. The currencies can also be sorted or paginated.
Inputs: fields, offset, limit, order, +4 more.
GetCurrenciesCodeC
Retrieve a currency by its code. You can expand the currency's relations or select the fields that should be returned.
Inputs: code, fields.
GetCustomersMeB
Retrieve the logged-in customer. You can expand the customer's relations or select the fields that should be returned.
Inputs: fields.
GetCustomersMeAddressesC
Retrieve the addresses of the logged-in customer. The addresses can be filtered by fields such as country_code. The addresses can also be sorted or paginated.
Inputs: fields, offset, limit, order, +4 more.
GetCustomersMeAddressesAddress_idC
Retrieve an address of the logged-in customer. You can expand the address's relations or select the fields that should be returned.
Inputs: address_id, fields.
GetOrdersC
Retrieve the orders of the logged-in customer. The orders can be filtered by fields such as id. The orders can also be sorted or paginated.
Inputs: fields, offset, limit, order, +4 more.
GetOrdersIdC
Retrieve an order by its ID. You can expand the order's relations or select the fields that should be returned.
Inputs: id, fields.
GetPaymentProvidersB
Retrieve a list of payment providers. You must provide the region_id query parameter to retrieve the payment providers enabled in that region.
Inputs: fields, offset, limit, order, +1 more.
GetProductCategoriesC
Retrieve a list of product categories. The product categories can be filtered by fields such as id. The product categories can also be sorted or paginated.
Inputs: fields, offset, limit, order, +12 more.
GetProductCategoriesIdB
Retrieve a product category by its ID. You can expand the product category's relations or select the fields that should be returned.
Inputs: id, fields, include_ancestors_tree, include_descendants_tree.
GetProductsC
Retrieve a list of products. The products can be filtered by fields such as id. The products can also be sorted or paginated.
Inputs: fields, offset, limit, order, +19 more.
GetProductsIdC
Retrieve a product by its ID. You can expand the product's relations or select the fields that should be returned.
Inputs: id, fields, region_id, country_code, +5 more.
GetProductTagsC
Retrieve a list of product tags. The product tags can be filtered by fields such as id. The product tags can also be sorted or paginated.
Inputs: fields, offset, limit, order, +7 more.
GetProductTagsIdC
Retrieve a product tag by its ID. You can expand the product tag's relations or select the fields that should be returned.
Inputs: id, fields.
GetProductTypesC
Retrieve a list of product types. The product types can be filtered by fields such as id. The product types can also be sorted or paginated.
Inputs: fields, offset, limit, order, +7 more.
GetProductTypesIdC
Retrieve a product type by its ID. You can expand the product type's relations or select the fields that should be returned.
Inputs: id, fields.
GetRegionsC
Retrieve a list of regions. The regions can be filtered by fields such as id. The regions can also be sorted or paginated.
Inputs: fields, offset, limit, order, +6 more.
GetRegionsIdC
Retrieve a region by its ID. You can expand the region's relations or select the fields that should be returned.
Inputs: id, fields.
GetReturnReasonsC
Retrieve a list of return reasons. The return reasons can be sorted or paginated.
Inputs: fields, offset, limit, order.
GetReturnReasonsIdC
Retrieve a return reason by its ID. You can expand the return reason's relations or select the fields that should be returned.
Inputs: id, fields.
GetShippingOptionsC
Retrieve a list of shipping options for a cart. The cart's ID is set in the required cart_id query parameter.
The shipping options also be sorted or paginated.
Inputs: fields, offset, limit, order, +4 more.
PostActor_typeAuth_providerA
Authenticate a customer and receive the JWT token to be used in the header of subsequent requests.
When used with a third-party provider, such as Google, the request returns a location property. You redirect to the specified URL in your storefront to continue authentication with the third-party service.
Inputs: auth_provider.
PostActor_typeAuth_providerCallbackB
This API route is used by your storefront or frontend application when a third-party provider redirects to it after authentication. It validates the authentication with the third-party provider and, if successful, returns an authentication token. All query parameters received from the third-party provider, such as code, state, and error, must be passed as query parameters to this route.
You can decode the JWT token using libraries like react-jwt in the storefront. If the decoded data doesn't have an actor_id property, then you must register the customer using the Create Customer API route passing the token in the request's Authorization header.
Inputs: auth_provider.
PostActor_typeAuth_provider_registerC
This API route retrieves a registration JWT token of a customer that hasn't been registered yet. The token is used in the header of requests that create a customer.
Inputs: auth_provider.
PostActor_typeAuth_providerResetPasswordA
Generate a reset password token for a customer. This API route doesn't reset the customer password or send them the reset instructions in a notification.
Instead, This API route emits the auth.password_reset event, passing it the token as a payload. You can listen to that event in a subscriber as explained in this guide, then send the customer a notification. The notification is sent using a Notification Module Provider, and it should have a URL that accepts a token query parameter, allowing the customer to reset their password from the storefront.
Use the generated token to update the customer's password using the Reset Password API route.
Inputs: auth_provider.
PostActor_typeAuth_providerUpdateC
Reset a customer's password using a reset-password token generated with the Generate Reset Password Token API route. You pass the token as a bearer token in the request's Authorization header.
Inputs: auth_provider.
PostAdminAuthTokenRefreshA
Refresh the authentication token of a customer. This is useful after authenticating a customer with a third-party service to ensure the token holds the new user's details, or when you don't want customers to re-login every day.
Inputs: no named parameters.
PostCartsD
Create a cart.
Inputs: fields.
PostCartsIdCompleteC
Complete a cart and place an order.
Inputs: id, fields.
PostCartsIdCustomerB
Set the customer of the cart. This is useful when you create the cart for a guest customer, then they log in with their account.
Inputs: id, fields.
PostCartsIdLineItemsC
Add a product variant as a line item in the cart.
Inputs: id, fields.
PostCartsIdLineItemsLine_idC
Update a line item's details in the cart.
Inputs: id, line_id, fields.
PostCartsIdPromotionsC
Add a list of promotions to a cart.
Inputs: id, fields.
PostCartsIdShippingMethodsB
Add a shipping method to a cart. Use this API route when the customer chooses their preferred shipping option.
Inputs: id, fields.
PostCartsIdTaxesC
Calculate the cart's tax lines and amounts.
Inputs: id, fields.
PostCustomersC
Register a customer. Use the /auth/customer/emailpass/register API route first to retrieve the registration token and pass it in the header of the request.
Inputs: fields.
PostOrdersIdTransferAcceptB
Accept an order to be transfered to a customer's account, which was specified when the transfer request was created. The transfer is requested previously either by the customer using the Request Order Transfer Store API route, or by the admin using the Request Order Transfer Admin API route.
Inputs: id, fields.
PostOrdersIdTransferCancelC
Cancel an order transfer that the logged-in customer previously requested using the Request Order Transfer API route.
Inputs: id, fields.
PostOrdersIdTransferDeclineC
Decline an order transfer previously requested, typically by the admin user using the Request Order Transfer Admin API route.
Inputs: id, fields.
PostOrdersIdTransferRequestC
Request an order to be transfered to the logged-in customer's account. The transfer is confirmed using the Accept Order Transfer API route.
Inputs: id, fields.
PostPaymentCollectionsC
Create a payment collection for a cart. This is used during checkout, where the payment collection holds the cart's payment sessions.
Inputs: fields.
PostPaymentCollectionsIdPaymentSessionsB
Initialize and add a payment session to a payment collection. This is used during checkout, where you create a payment collection for the cart, then initialize a payment session for the payment provider that the customer chooses.
Inputs: id, fields.
PostReturnB
Create a return for an order's items. The admin receives the return and process it from their side.
Inputs: no named parameters.
PostSessionA
Set the cookie session ID of a customer. The customer must be previously authenticated with the /auth/customer/{provider} API route first, as the JWT token is required in the header of the request.
Inputs: no named parameters.
PostShippingOptionsIdCalculateC
Calculate the price of a shipping option in a cart.
Inputs: id, fields.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 48 tools
Every tool has a distinct purpose targeting specific resources and actions, such as GetCartsId for retrieving a cart by ID, PostCarts for creating a cart, and PostCartsIdComplete for completing a cart. The naming and descriptions clearly differentiate between retrieval, creation, update, and other operations, with no overlapping or ambiguous tools.
Tool names follow a highly consistent verb_noun pattern throughout, using 'Get' for retrieval, 'Post' for creation or action, and specific identifiers like 'Id' or 'Code'. Examples include GetProductsId, PostCartsIdLineItems, and PostActor_typeAuth_provider, all adhering to a predictable and readable convention.
With 48 tools, the count is excessive for an MCP server, making it cumbersome for agents to navigate and increasing the risk of misselection. While the server covers a broad e-commerce domain, a more streamlined set of 15-25 tools would be more appropriate for usability and coherence.
The tool set provides comprehensive coverage of the e-commerce domain, including CRUD operations for carts, products, orders, customers, and authentication, as well as specialized actions like payment processing, shipping, and returns. There are no obvious gaps, ensuring agents can handle full workflows without dead ends.
Maintenance
Related MCP Connectors
A Model Context Protocol server for Wix AI tools
Model Context Protocol server for Studex tools, notifications, and profile integrations
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Hosted MCP server for AI-driven data ops. Create apps, manage schemas, and CRUD structured data.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA server that implements the Model Context Protocol, providing a standardized way to connect AI models to different data sources and tools.12MIT
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables real-time communication using Server-Sent Events (SSE), providing standardized model management and resource templating capabilities.-
- AlicenseNot gradedqualityDmaintenanceA server that implements the Model Context Protocol (MCP) with StreamableHTTP transport, enabling standardized interaction with model services through a RESTful API interface.2MIT
- AlicenseNot gradedqualityDmaintenanceA production-ready Model Context Protocol server for interacting with Cosmic headless CMS, providing comprehensive tools for managing objects, types, and media in your Cosmic bucket.MIT