mo9rani/magento2-mcp-oauth-server

Magento 2 MCP Server

A standalone HTTP server that provides Model Context Protocol (MCP) tools for Magento 2 API integration.

Note: This is a fork of the original Magento 2 MCP Server project, streamlined and configured to support OAuth 1.0a key-based authentication for secure API access.

Features

Product Features

• Query product information by SKU
• Search for products with pagination
• Get product stock information
• Get product attributes

Order and Revenue Features

• Get order count for specific date ranges
• Get revenue for specific date ranges with tax options
• Get product sales statistics including quantity sold and top-selling products
• Support for relative date expressions like "today", "yesterday", "last week", "this month", "YTD"
• Support for country filtering using both country codes and country names

Prerequisites

• Node.js (v14 or higher)
• A Magento 2 instance with REST API access
• Magento 2 Admin API token

Installation

npm install

Configuration

1. Copy .env.example to .env:

cp .env.example .env

2. Update .env with your Magento 2 credentials:

MAGENTO_BASE_URL=https://your-magento-store.com
MAGENTO_ADMIN_TOKEN=your-admin-token-here
PORT=3000

Getting Admin Token from Magento

1. Go to Magento Admin: System > Extensions > Integrations
2. Click "Add New Integration"
3. Fill in the Integration Info:
   • Name: "MCP Server" (or any name)
   • Your Password: (your admin password)
4. Go to "API" tab and select the resources you want to grant access to
5. Save and Activate the integration
6. Copy the "Access Token" - this is your MAGENTO_ADMIN_TOKEN

Usage

Start the HTTP server:

npm start

The server will run on http://localhost:3000 (or your configured PORT).

HTTP API Endpoints

Health Check

GET /health

Returns server health status and Magento connection info.

List Available Tools

GET /tools

Returns all available MCP tools with their schemas.

Execute Tool

POST /tools/execute
Content-Type: application/json

{
  "tool": "tool_name",
  "arguments": {
    "arg1": "value1"
  }
}

Available Tools

Product Tools

• get_product_by_sku: Get detailed information about a product by its SKU
• search_products: Search for products using query string with pagination

Order and Revenue Tools

• get_order_count: Get the number of orders for a given date range
• get_revenue: Get the total revenue for a given date range (with optional tax)
• get_product_sales: Get statistics about products sold in a date range

Example Usage

Using with HTTP Client (curl)

# Health check
curl http://localhost:3000/health

# List tools
curl http://localhost:3000/tools

# Search products
curl -X POST http://localhost:3000/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "search_products",
    "arguments": {
      "query": "shirt",
      "page_size": 10,
      "current_page": 1
    }
  }'

# Get revenue
curl -X POST http://localhost:3000/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "get_revenue",
    "arguments": {
      "date_range": "last month",
      "include_tax": true
    }
  }'

Using with Mastra Framework

See your project's integration at packages/agents/src/mastra/config/mcp.ts and packages/agents/src/mastra/tools/magento-client.ts for TypeScript client implementation examples.

Development

SSL Certificate Verification

For development purposes, the server may be configured to bypass SSL certificate verification. In production, use proper SSL certificates.

License

ISC