jayankaghosh/magento-mcp-server

Magento MCP Server

A Model Context Protocol (MCP) server that provides dynamic access to Magento e-commerce data for ChatGPT and other AI assistants. This server enables natural language queries about your Magento store's catalog, sales, and customer data.

Features

🛍️ Catalog Analysis

• Dynamic Product Queries: Ask questions like "How many products don't have images?" or "What's the average price of simple products?"
• Category Insights: Analyze category hierarchies, find categories with low product counts
• Flexible Filtering: Filter products by any field (status, type, price, dates, custom attributes)

📊 Sales Analytics

• Order Analysis: Get insights on average order value, sales by day of week, monthly trends
• Product Performance: Find top-selling products, analyze sales by time periods
• Revenue Metrics: Calculate revenue distributions, customer purchase patterns

👥 Customer Intelligence

• Behavior Analysis: Segment customers by value, frequency, recency
• Fraud Detection: Identify suspicious email patterns and potential fraud indicators
• Target Marketing: Find high-value customers, at-risk customers, or customers matching specific criteria

Installation

1. Clone and Install Dependencies

cd /path/to/magento-mcp-server
npm install

2. Configure Environment

cp .env.example .env

Edit .env with your Magento credentials:

MAGENTO_BASE_URL=https://your-magento-store.com
MAGENTO_ACCESS_TOKEN=your_admin_access_token_here
RATE_LIMIT=10

3. Build the Project

npm run build

Getting Magento Access Token

1. Log into Magento Admin Panel
2. Navigate to System > Extensions > Integrations
3. Create New Integration:
   • Name: "MCP Server Integration"
   • Your Password: [your admin password]
   • Resources: Select "All" or specific resources you need
4. Activate the Integration and copy the Access Token

Usage with ChatGPT

1. Add to ChatGPT Configuration

Add this to your ChatGPT MCP configuration file (usually ~/.config/chatgpt/mcp.json):

{
  "mcpServers": {
    "magento": {
      "command": "node",
      "args": ["/path/to/magento-mcp-server/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

2. Start Using Natural Language Queries

Once connected, you can ask ChatGPT questions like:

Catalog Questions

• "How many products are there without any images?"
• "What's the price range of all active products?"
• "Show me categories with less than 20 products"
• "How many simple products vs configurable products do I have?"

Sales Questions

• "What's my average order value this year?"
• "Which day of the week has the most orders?"
• "What are my top 10 selling products in July and August?"
• "Show me monthly revenue trends for 2024"

Customer Questions

• "How many customers have suspicious email patterns?"
• "Who are my most valuable customers?"
• "Which customers haven't ordered in over 6 months?"
• "Find customers with lifetime value over $1000"

Available Tools

The server provides these dynamic tools that ChatGPT can use:

Catalog Tools

• get_all_products - Retrieve products with filtering
• get_all_categories - Get category hierarchy
• analyze_products - Custom product analysis with grouping and metrics
• analyze_categories - Custom category analysis

Sales Tools

• get_all_orders - Retrieve orders with filtering
• analyze_orders - Custom order analysis with time grouping
• analyze_product_sales - Product sales performance analysis

Customer Tools

• get_all_customers - Retrieve customers with filtering
• analyze_customers - Custom customer analysis
• analyze_customer_behavior - Customer segmentation and behavior analysis
• find_target_customers - Find customers matching specific criteria

Example Queries and How They Work

"How many products don't have images?"

ChatGPT will use analyze_products with metrics: ['without_images'] to get this information.

"What's my average order value this month?"

ChatGPT will use analyze_orders with date filters and calculate the average from the results.

"Which customers should I call to congratulate for being valuable?"

ChatGPT will use find_target_customers with minLifetimeValue and other criteria to identify VIP customers.

Development

Running in Development Mode

npm run dev

Building

npm run build

Project Structure

src/
├── index.ts              # Main MCP server entry point
├── config.ts             # Environment configuration
├── magento-client.ts     # Magento API client
└── tools/
    ├── catalog-tools.ts  # Product and category analysis
    ├── sales-tools.ts    # Order and sales analysis
    └── customer-tools.ts # Customer analysis

Security Considerations

• API Token Security: Never commit your .env file. The access token has admin privileges.
• Rate Limiting: The server includes rate limiting to prevent API abuse.
• Network Security: Ensure your Magento instance is properly secured with HTTPS.

Troubleshooting

Common Issues

1. "Configuration validation failed"

   • Check your .env file has all required variables
   • Verify your Magento URL is correct and accessible

2. "Failed to get products/orders/customers"

   • Verify your access token has the required permissions
   • Check if your Magento API is accessible
   • Ensure rate limits aren't being exceeded

3. "Connection refused"

   • Verify your Magento base URL is correct
   • Check if your server can reach the Magento instance

Debug Mode

Set NODE_ENV=development for more detailed error messages.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check the troubleshooting section above
2. Review Magento API documentation
3. Create an issue in the repository

Note: This server provides read-only access to your Magento data. It does not modify any store data, only retrieves and analyzes it for insights.