PHPackages                             freento/module-mcp - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. freento/module-mcp

ActiveMagento2-module[Framework](/categories/framework)

freento/module-mcp
==================

MCP (Model Context Protocol) server for Magento 2 - All-in-one module

1.1.0(1mo ago)10123MITPHPPHP >=8.1

Since Feb 3Pushed 1mo agoCompare

[ Source](https://github.com/Freento/Magento-2-Mcp)[ Packagist](https://packagist.org/packages/freento/module-mcp)[ RSS](/packages/freento-module-mcp/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (2)Dependencies (6)Versions (3)Used By (0)

Freento MCP for Magento 2 — User Guide
======================================

[](#freento-mcp-for-magento-2--user-guide)

Connect your Magento 2 store to AI assistants like Claude and ChatGPT using the Model Context Protocol (MCP).

Table of Contents
-----------------

[](#table-of-contents)

- [Overview](#overview)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
    - [Claude Code](#claude-code)
    - [Claude Desktop](#claude-desktop)
    - [ChatGPT](#chatgpt)
- [Available Tools](#available-tools)
- [Usage Examples](#usage-examples)
- [Filtering & Operators](#filtering--operators)
- [Aggregation & Analytics](#aggregation--analytics)
- [Troubleshooting](#troubleshooting)
- [Security](#security)

Overview
--------

[](#overview)

Freento MCP is a Magento 2 extension that implements the [Model Context Protocol](https://modelcontextprotocol.io/) — 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

**How it works:**

```
┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  AI Assistant   │  HTTP   │  Freento MCP    │         │   Magento 2 /   │
│  (Claude/GPT)   │ ◄─────► │  Server         │ ◄─────► │Server Resources │
└─────────────────┘ JSON-RPC└─────────────────┘         └─────────────────┘

```

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
------------

[](#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
------------

[](#installation)

### Via Composer (Recommended)

[](#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

[](#manual-installation)

1. Download the module and extract to `app/code/Freento/Mcp/`
2. Enable the module:

```
php bin/magento module:enable Freento_Mcp
php bin/magento setup:upgrade
php bin/magento cache:flush
```

### Verify Installation

[](#verify-installation)

```
php bin/magento module:status Freento_Mcp
```

Expected output: `Module is enabled`

Configuration
-------------

[](#configuration)

### Step 1: Create ACL Role

[](#step-1-create-acl-role)

1. In Magento Admin, go to **System > Freento MCP > ACL Rules**
2. Click **Add New Role**
3. Enter a name (e.g., "AI Assistant")
4. Select which tools the role can access:
    - Sales tools (orders, quotes, credit memos)
    - Catalog tools (products, stock)
    - Customer tools
    - Admin tools
    - System tools
5. **Save** the role

### Step 2: Create OAuth Client

[](#step-2-create-oauth-client)

1. Go to **System > Freento MCP > AI MCP Clients**
2. Click **Add New Client**
3. Enter a name (e.g., "Claude Code")
4. Select the ACL Role created in Step 1
5. **Save** the client
6. Copy the **Client ID** and **Client Secret**

### Step 3: Generate Access Token

[](#step-3-generate-access-token)

1. Open the OAuth Client you created
2. Click **Generate OTP** — copy the one-time password (valid 24 hours)
3. Click **Generate Token** — enter the OTP when prompted
4. Copy the generated **Access Token**

### Claude Code

[](#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

[](#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

[](#chatgpt-and-other-web-clients)

For web-based AI tools that support OAuth 2.0:

1. Register your store's MCP endpoint: `https://your-store.com/freento_mcp/index/index`
2. Enter the **Client ID** and **Client Secret** from Step 2
3. When prompted to authorize, enter the **OTP** generated from the OAuth Client page
4. Complete the OAuth authorization flow

Available Tools
---------------

[](#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

[](#sales-tools)

ToolDescription`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

[](#marketing-tools)

ToolDescription`get_cart_price_rules`Query cart price rules`get_coupons`Query coupons### Catalog Tools

[](#catalog-tools)

ToolDescription`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

[](#customer-tools)

ToolDescription`get_customers`Query customer accounts### Admin Tools

[](#admin-tools)

ToolDescription`get_admins`List admin users and their roles`get_locked_admins`Find locked admin accounts (failed login attempts)### System Tools

[](#system-tools)

ToolDescription`get_system_versions`Get Magento, PHP, MySQL, Redis, OpenSearch versions`get_stores`Get store hierarchy (websites, store groups, store views)Usage Examples
--------------

[](#usage-examples)

Once configured, you can ask your AI assistant questions in natural language:

### Orders & Sales

[](#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

[](#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

[](#customers)

```
"How many customers registered this month?"
"Find customer with email jane@example.com"
"List customers in the Wholesale group"

```

### System & Admin

[](#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

[](#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

[](#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
-------------------------

[](#filtering--operators)

All list tools support powerful filtering via the `filters` parameter.

### Filter Structure

[](#filter-structure)

```
{
  "filters": {
    "field_name": { "operator": "value" }
  }
}
```

### Available Operators

[](#available-operators)

OperatorDescriptionExample`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

[](#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

[](#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
---------------------------

[](#aggregation--analytics)

The `get_orders` tool supports aggregation for analytics:

### Parameters

[](#parameters)

ParameterValuesDescription`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

[](#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
---------------

[](#troubleshooting)

### Tools not appearing in AI assistant

[](#tools-not-appearing-in-ai-assistant)

1. Verify the module is enabled:

    ```
    php bin/magento module:status Freento_Mcp
    ```
2. Flush Magento cache:

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

### "Authentication failed" error

[](#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

[](#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

[](#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

[](#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
--------

[](#security)

### Best Practices

[](#best-practices)

1. **Use HTTPS** — Always use HTTPS in production to encrypt API communications
2. **Minimal Permissions** — Grant only the tools needed for your use case via ACL Roles
3. **Separate Clients** — Create separate OAuth Clients for different users/purposes
4. **Regular Audits** — Periodically review active clients and disable unused ones
5. **Token Rotation** — Regenerate access tokens periodically

### Token Security

[](#token-security)

- Never commit tokens to version control
- Use environment variables or secure secret management
- Rotate tokens periodically
- Revoke tokens immediately if compromised

Support
-------

[](#support)

**Contact:**

License
-------

[](#license)

MIT License — see [LICENSE](LICENSE) for details.

###  Health Score

41

—

FairBetter than 89% of packages

Maintenance90

Actively maintained with recent releases

Popularity16

Limited adoption so far

Community5

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~51 days

Total

2

Last Release

52d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/98f431f566f9a6d2cbe0e346430548851a8aba22f9bdf8efef8429a549b84513?d=identicon)[Freento](/maintainers/Freento)

### Embed Badge

![Health badge](/badges/freento-module-mcp/health.svg)

```
[![Health](https://phpackages.com/badges/freento-module-mcp/health.svg)](https://phpackages.com/packages/freento-module-mcp)
```

###  Alternatives

[dotdigital/dotdigital-magento2-extension

Dotdigital for Magento 2

50374.2k18](/packages/dotdigital-dotdigital-magento2-extension)[hyva-themes/magento2-react-checkout

Highly customizable Magento 2 Checkout, built with React

189169.8k1](/packages/hyva-themes-magento2-react-checkout)[mollie/magento2

Mollie Payment Module for Magento 2

1121.6M10](/packages/mollie-magento2)[swissup/module-search-mysql-legacy

Legacy mysql search for magento 2.4

10483.0k](/packages/swissup-module-search-mysql-legacy)[mage-os/module-inventory-reservations-grid

Add a grid with the list of inventory reservations.

126.8k](/packages/mage-os-module-inventory-reservations-grid)[o2ti/sigep-web-carrier

O2TI - Sigep Web Carrier

141.5k](/packages/o2ti-sigep-web-carrier)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)