Magento MCP Server
by jayankaghosh
README.md
# 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**
```bash
cd /path/to/magento-mcp-server
npm install
```
2. **Configure Environment**
```bash
cp .env.example .env
```
Edit `.env` with your Magento credentials:
```env
MAGENTO_BASE_URL=https://your-magento-store.com
MAGENTO_ACCESS_TOKEN=your_admin_access_token_here
RATE_LIMIT=10
```
3. **Build the Project**
```bash
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`):
```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
```bash
npm run dev
```
### Building
```bash
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.
This server cannot be deployed
Maintenance
ActivityInactive
ResponsivenessNo recent community issues