Freento Mcp Server

Overview
Freento MCP is a Magento 2 extension that implements the Model Context Protocol — an open standard for connecting AI assistants to external data sources. With this extension, you can:

Query orders, products, customers, and inventory using natural language
Generate sales reports and analytics on the fly
Monitor system health (PHP, MySQL, cache, search engine versions)
Audit admin users and security settings

The MCP server acts as a secure bridge between AI assistants and your Magento installation, providing access to various store resources including the database, configuration, and other Magento subsystems.

Requirements
Magento 2.4.x (Open Source or Commerce)
PHP 8.1 or higher
An MCP-compatible AI client (Claude Code, Claude Desktop, or ChatGPT with MCP plugin)
Installation
Via Composer (Recommended)
composer require freento/module-mcp
php bin/magento module:enable Freento_Mcp
php bin/magento setup:upgrade
php bin/magento cache:flush
Manual Installation
Download the module and extract to app/code/Freento/Mcp/
Enable the module:
php bin/magento module:enable Freento_Mcp
php bin/magento setup:upgrade
php bin/magento cache:flush
Verify Installation
php bin/magento module:status Freento_Mcp
Expected output: Module is enabled

Configuration
Step 1: Create ACL Role
In Magento Admin, go to System > Freento MCP > ACL Rules
Click Add New Role
Enter a name (e.g., "AI Assistant")
Select which tools the role can access:
Sales tools (orders, quotes, credit memos)
Catalog tools (products, stock)
Customer tools
Admin tools
System tools
Save the role
Step 2: Create OAuth Client
Go to System > Freento MCP > AI MCP Clients
Click Add New Client
Enter a name (e.g., "Claude Code")
Select the ACL Role created in Step 1
Save the client
Copy the Client ID and Client Secret
Step 3: Generate Access Token
Open the OAuth Client you created
Click Generate OTP — copy the one-time password (valid 24 hours)
Click Generate Token — enter the OTP when prompted
Copy the generated Access Token
Claude Code
Add to your project's .mcp.json:

{
"mcpServers": {
"magento": {
"type": "http",
"url": "https://your-store.com/freento_mcp/index/index",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
}
}
}
Then reconnect MCP in Claude Code:

/mcp
Claude Desktop
Edit your Claude Desktop config (~/.config/claude/claude_desktop_config.json on Linux/Mac or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
"mcpServers": {
"magento": {
"type": "http",
"url": "https://your-store.com/freento_mcp/index/index",
"headers": {
"Authorization": "Bearer YOUR_ACCESS_TOKEN"
}
}
}
}
Restart Claude Desktop to apply changes.

ChatGPT and Other Web Clients
For web-based AI tools that support OAuth 2.0:

Register your store's MCP endpoint: https://your-store.com/freento_mcp/index/index
Enter the Client ID and Client Secret from Step 2
When prompted to authorize, enter the OTP generated from the OAuth Client page
Complete the OAuth authorization flow
Available Tools
Each tool supports flexible filtering, sorting, and pagination. Combined with AI, these capabilities become virtually unlimited — the AI can execute multiple queries, cross-reference data, group and aggregate results, and provide intelligent analysis.

AI can:

Run multiple queries across different entities in one conversation
Filter by any field using operators: eq, neq, in, like, gt, gte, lt, lte
Sort and paginate results
Aggregate with sum, count, avg, min, max
Group by field or time period (day, month)
Combine and analyze data from multiple sources
Sales Tools
Tool Description
get_orders Query orders with filtering, pagination, and aggregation
get_order_items Get order line items (products in orders)
get_quotes Query shopping carts (active and abandoned)
get_quote_items Get cart line items
get_creditmemos Query credit memos
Marketing Tools
Tool Description
get_cart_price_rules Query cart price rules
get_coupons Query coupons
Catalog Tools
Tool Description
get_products Query products with attribute filtering
get_categories Query product categories
get_product_prices Get product prices by customer group and website
get_product_tier_prices Get tier price rules (quantity-based discounts)
get_tax_rules Get tax rules and rates
get_stock_single_stock Get inventory/stock levels
Customer Tools
Tool Description
get_customers Query customer accounts
Admin Tools
Tool Description
get_admins List admin users and their roles
get_locked_admins Find locked admin accounts (failed login attempts)
System Tools
Tool Description
get_system_versions Get Magento, PHP, MySQL, Redis, OpenSearch versions
get_stores Get store hierarchy (websites, store groups, store views)
Usage Examples
Once configured, you can ask your AI assistant questions in natural language:

Orders & Sales
"How many orders were placed last month?"
"Show me the 10 most recent orders"
"Find all orders over $500 that are still processing"
"What's the total revenue by payment method this year?"
"List orders for customer john@example.com"
Products & Inventory
"Show me out of stock products"
"Find products with SKU starting with 'ABC'"
"List products with less than 10 items in stock"
"Get all configurable products updated this week"
Customers
"How many customers registered this month?"
"Find customer with email jane@example.com"
"List customers in the Wholesale group"
System & Admin
"What PHP version is running?"
"Show me all admin users"
"Are there any locked admin accounts?"
"What search engine is configured?"
Analytics & Reports
"Revenue by month for the last 12 months"
"Top 10 customers by total order value"
"Average order value by payment method"
"Order count by status"
Advanced AI-Powered Analysis
The real power comes from combining data with AI reasoning. Ask complex business questions and get actionable insights:

Customer Intelligence:

"Analyze my top 10 customers from the last 6 months. Who are they,
what do they buy, and how can I increase sales?"
The AI will retrieve the data and provide analysis like:

Mike Johnson — $4,250 total, 8 orders Profile: Professional drummer buying cymbals and drumsticks every 5-6 weeks

Recommendation: Set up auto-replenishment for drumsticks, offer early access to new cymbal arrivals, consider a "drummer's loyalty" discount tier.

Churn Prevention:

"Find customers who were active but haven't ordered in 90 days.
What patterns do you see and how can I win them back?"
Inventory Optimization:

"Analyze sales velocity vs current stock levels.
What should I reorder and what's at risk of becoming dead stock?"
Revenue Opportunities:

"What patterns exist in high-value orders? How can I get more customers
to spend at that level?"
Abandoned Cart Analysis:

"Look at abandoned carts from this week. What are people leaving behind
and what might be causing it?"
This transforms your store data into strategic business intelligence — insights that would typically require hours with spreadsheets or a dedicated analyst.

Filtering & Operators
All list tools support powerful filtering via the filters parameter.

Filter Structure
{
"filters": {
"field_name": { "operator": "value" }
}
}
Available Operators
Operator Description Example
eq Equals {"status": {"eq": "processing"}}
neq Not equals {"status": {"neq": "canceled"}}
in In list {"status": {"in": ["processing", "complete"]}}
nin Not in list {"status": {"nin": ["canceled", "closed"]}}
like SQL LIKE pattern {"email": {"like": "%@gmail.com"}}
nlike SQL NOT LIKE {"sku": {"nlike": "TEST%"}}
gt Greater than {"grand_total": {"gt": 100}}
gte Greater or equal {"qty": {"gte": 10}}
lt Less than {"created_at": {"lt": "2024-01-01"}}
lte Less or equal {"price": {"lte": 50}}
Combining Filters
Multiple filters are combined with AND logic:

{
"filters": {
"status": {"in": ["processing", "pending"]},
"grand_total": {"gte": 100},
"created_at": {"gte": "2024-01-01"}
}
}
Date Filtering
Use YYYY-MM-DD or YYYY-MM-DD HH:MM:SS format:

{
"filters": {
"created_at": {"gte": "2024-01-01", "lt": "2024-02-01"}
}
}
Aggregation & Analytics
The get_orders tool supports aggregation for analytics:

Parameters
Parameter Values Description
function count, sum, avg, min, max Aggregation function
field grand_total, total_qty_ordered, total_item_count Field to aggregate
group_by status, month, day, customer_email, store_id, payment_method Grouping
Examples
Total order count:

{"function": "count"}
Revenue by month:

{
"function": "sum",
"field": "grand_total",
"group_by": "month"
}
Average order value by payment method:

{
"function": "avg",
"field": "grand_total",
"group_by": "payment_method"
}
Top 10 customers by spending:

{
"function": "sum",
"field": "grand_total",
"group_by": "customer_email",
"filters": {
"status": {"nin": ["canceled", "closed"]}
},
"limit": 10
}
Troubleshooting
Tools not appearing in AI assistant
Verify the module is enabled:

php bin/magento module:status Freento_Mcp
Flush Magento cache:

php bin/magento cache:flush
Reconnect MCP in your AI client (e.g., /mcp in Claude Code)

"Authentication failed" error
Verify your access token is correct
Check the OAuth Client is enabled in Magento Admin
Regenerate the token if it has expired
"Access denied" error
The ACL Role lacks required permissions. Edit the ACL Role in System > Freento MCP > ACL Rules and grant access to the necessary tools.

Connection timeout
Verify your Magento store is accessible from the internet
Check firewall rules allow incoming connections
For local development, use a tunnel service like ngrok
Test the endpoint manually
curl -X POST https://your-store.com/freento_mcp/index/index \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Security
Best Practices
Use HTTPS — Always use HTTPS in production to encrypt API communications

Minimal Permissions — Grant only the tools needed for your use case via ACL Roles

Separate Clients — Create separate OAuth Clients for different users/purposes

Regular Audits — Periodically review active clients and disable unused ones

Token Rotation — Regenerate access tokens periodically

Anonymity Mode — Enable anonymity mode in Stores > Configuration > Freento MCP > Privacy to hide PII fields (emails, names) from MCP tool responses. Since AI assistants connecting via MCP are third-party services, it is recommended to enable this mode to prevent customer personal data from being transmitted externally unless explicitly needed.

Token Security
Never commit tokens to version control
Use environment variables or secure secret management
Rotate tokens periodically
Revoke tokens immediately if compromised
Support
Contact: https://freento.com/contact