The J2Commerce MCP Server plugin lets AI assistants such as Claude, ChatGPT and Cursor work with your store through the Model Context Protocol (MCP), an open standard for connecting AI applications to other software. An assistant can read your products, orders, customers, sales figures, coupons and settings. It can also change them, but only where you allow it.
Every connection signs in as a Joomla user account, and the assistant can do only what that account is permitted to do in J2Commerce. Reading is on for six tool groups by default. Writing is off until you switch it on for a group.
Requirements
- J2Commerce 6.6.6 or later installed and active
- PHP 8.3 or later
- A Joomla user account for the assistant to sign in as, with an API token (see Signing In)
- For STDIO: PHP command-line access, and an AI tool running on the same computer as the site
- For HTTP: an AI tool that can reach your site over the web
Purchase and Download
The J2Commerce MCP Server is a separate add-on available from the MCP Server on the J2Commerce Extensions Store. It is not included with the core J2Commerce 6 component.
Step 1: Go to the J2Commerce website -> Extensions.
Step 2: Locate the J2Commerce MCP Server, click View Details, then Add to Cart -> Checkout.
Step 3: Go to My Downloads under your profile menu at the top right corner and find the plugin. Click Available Versions -> View Files -> Download Now.
Install the Plugin
In the Joomla administrator, go to System -> Install -> Extensions. Upload the plugin ZIP file, or use the Install from URL option.
Enable the Plugin
- Go to System -> Manage -> Plugins.
- Search for J2Commerce MCP Server.
- If the status icon is not a green checkmark, click it to enable the plugin.
Configure the Plugin
Click the plugin name to open its settings. The toolbar has a Dashboard button that opens the MCP dashboard and a Help button that opens this page. The same dashboard is available from the MCP Server tile on the J2Commerce dashboard.
Tip
Click Toggle Inline Help in the toolbar to show a description below each field.
| Setting | What It Does | Default | Options |
|---|---|---|---|
| Enabled Tool Groups | The groups of tools an assistant can read from. A group you leave out is removed from the tool list. | Products, Orders, Customers, Analytics, Coupons, Shipping & Payment | Products, Orders, Customers, Analytics, Coupons, Shipping & Payment, Reference Data, Store Settings, Other Extensions |
| Allow AI to Change (Write) These Groups | The groups an assistant may change data in. Only groups ticked under Enabled Tool Groups can be selected, and the signed-in account still needs the matching J2Commerce permission. Upgrades leave this empty. | Empty (read only) | Products, Orders, Customers, Coupons, Store Settings, Other Extensions |
| Bulk Change Limit | The most products one bulk price, stock or publish call may change. A request that matches more is refused and nothing is changed. Naming products one by one is capped at 50 per call whatever this is set to. Shown only when a write group is selected. | 100 | 1 to 500 |
| Allowed Transports | How an assistant may connect. Both need a Joomla API token. | STDIO only | HTTP (via com_ajax), STDIO (CLI for local AI tools) |
| Action Log Retention (Days) | How long the MCP action log, which records every tool call, is kept. Older entries are removed automatically. | 90 | 0 to 3650. 0 keeps the log forever. |
| Debug Mode | Writes connection detail to the Joomla log. Useful when a connection fails. | No | Yes, No |
Warning
HTTP exposes a public endpoint on your site. Anyone holding a valid token can read whatever store, order and customer data that account is allowed to see. Turn HTTP on only if you accept that, and keep it off if every assistant runs on the same computer as the site.
Only the Products, Orders, Customers, Coupons, Store Settings and Other Extensions groups have tools that change data. Analytics, Shipping & Payment and Reference Data are read only. Other Extensions holds tools that other J2Commerce plugins add; it is empty until one does.
Signing In
Every request needs a signed-in account. A request with no token, or an invalid one, is refused with an authentication error and no tool, resource or prompt is listed.
API Tokens
The simplest way to connect is a Joomla API token for the account the assistant will use. The plugin accepts it as an Authorization: Bearer header or an X-Joomla-Token header. The STDIO connection reads it from the JOOMLA_API_KEY environment variable.
To get a token:
- Open the MCP dashboard and find the Connect an AI Assistant panel.
- Click Create AI Token. If you already have one, the button reads Reset AI Token, and resetting disconnects every assistant using the old token.
- Copy the configuration shown in the panel into your AI tool (see Connecting an AI Tool).
You can also create a token from your own user profile with Open My Profile. A token carries the permissions of the account that owns it, so treat it like a password.
The panel tells you what stands in the way when a token cannot work. These are the messages and what to do:
| Message | What to Do |
|---|---|
| The API Authentication - Joomla Token plugin is disabled | Enable it in the Plugins manager. |
| The User - Joomla API Token plugin is disabled | Enable it in the Plugins manager so tokens can be created. |
| This site has no secret configured | Check the secret value in configuration.php. |
| Your user group is not allowed to hold API tokens | Change the Allowed User Groups setting on the User - Joomla API Token plugin. |
| You do not have an API token yet | Click Create AI Token. |
| Your API token exists but is switched off | Turn it back on from your user profile. |
| Your account cannot log in to the API | Grant the API Login permission to your user group in Global Configuration. |
An account that is not a Super User needs the API Login permission (core.login.api) to connect by any method.
Signing In With a Joomla Account
The separate MCP Connect plugin (plg_system_j2commerceoauth) lets an assistant ask you for permission through a sign-in and consent screen, so you never paste a token into it. It is required for assistants that run on someone else's servers, such as ChatGPT connectors.
An assistant connected this way is held to what you approved, even where your account could do more. Install it alongside the MCP Server and add HTTP to Allowed Transports; without HTTP, assistants cannot complete the connection.
Connecting an AI Tool
Every connection is made with the same three things: how to reach the site, your token, and the tool's own configuration file. The Connect an AI Assistant panel on the MCP dashboard builds the first two for you and fills in your token.
Choosing the Right Transport
STDIO is the right choice when your AI tool runs on the same computer as your Joomla site. The tool starts the plugin's command-line script and talks to it directly, so nothing is exposed on the web. It is the only transport enabled by default.
HTTP is for a site on a remote server, or an AI service that connects over the web. Add HTTP (via com_ajax) to Allowed Transports first, and read the warning above.
The panel produces three configurations:
- Client Configuration: a STDIO setup that runs the script with
phpand setsJOOMLA_API_KEY. - Connect From Anywhere: an HTTP setup with the endpoint URL and an
Authorization: Bearerheader. It is shown only when HTTP is allowed. - Older Clients: the same HTTP connection through the free
mcp-remotebridge, for tools that only run a program on your own computer. It needs Node.js on that computer and installs nothing on the server.
The HTTP endpoint is:
https://your-site.com/index.php?option=com_ajax&plugin=j2commercemcp&group=system&format=raw
The STDIO script is plugins/system/j2commercemcp/cli/j2commercemcp.php inside your Joomla folder. The panel shows its full path on your server.
The per-tool file locations and layouts below come from those tools, not from J2Commerce, and tools change them. If a tool's own documentation differs, follow the tool.
Claude Code
Claude Code reads MCP servers from a .mcp.json file in your project root or from its global settings.
STDIO transport (same computer):
{
"mcpServers": {
"j2commerce": {
"type": "stdio",
"command": "php",
"args": [
"/path/to/your/joomla/plugins/system/j2commercemcp/cli/j2commercemcp.php"
],
"env": {
"JOOMLA_API_KEY": "YOUR_TOKEN_HERE"
}
}
}
}
HTTP transport:
{
"mcpServers": {
"j2commerce": {
"type": "http",
"url": "https://your-site.com/index.php?option=com_ajax&plugin=j2commercemcp&group=system&format=raw",
"headers": {
"Authorization": "Bearer YOUR_TOKEN_HERE"
}
}
}
}
Replace /path/to/your/joomla with the absolute path to your Joomla folder, for example /var/www/html/joomla.
Claude Desktop
Claude Desktop reads its MCP configuration from claude_desktop_config.json:
- Windows:
%APPDATA%\Claude\claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
STDIO transport (same computer):
{
"mcpServers": {
"j2commerce": {
"command": "php",
"args": [
"/path/to/your/joomla/plugins/system/j2commercemcp/cli/j2commercemcp.php"
],
"env": {
"JOOMLA_API_KEY": "YOUR_TOKEN_HERE"
}
}
}
}
Windows example:
{
"mcpServers": {
"j2commerce": {
"command": "php",
"args": [
"C:\\path\\to\\joomla\\plugins\\system\\j2commercemcp\\cli\\j2commercemcp.php"
],
"env": {
"JOOMLA_API_KEY": "YOUR_TOKEN_HERE"
}
}
}
}
Windows paths in JSON must use double backslashes (\\).
HTTP through the bridge (remote site):
{
"mcpServers": {
"j2commerce": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://your-site.com/index.php?option=com_ajax&plugin=j2commercemcp&group=system&format=raw",
"--header",
"Authorization: Bearer YOUR_TOKEN_HERE"
]
}
}
}
After saving the file, restart Claude Desktop. The J2Commerce tools appear in the tool selector.
Cursor
Cursor reads a .cursor/mcp.json file in your project root, or its global settings.
STDIO transport (same computer):
{
"mcpServers": {
"j2commerce": {
"command": "php",
"args": [
"/path/to/your/joomla/plugins/system/j2commercemcp/cli/j2commercemcp.php"
],
"env": {
"JOOMLA_API_KEY": "YOUR_TOKEN_HERE"
}
}
}
}
HTTP transport:
{
"mcpServers": {
"j2commerce": {
"url": "https://your-site.com/index.php?option=com_ajax&plugin=j2commercemcp&group=system&format=raw",
"transport": "http",
"headers": {
"Authorization": "Bearer YOUR_TOKEN_HERE"
}
}
}
}
After adding the configuration, open Cursor Settings, go to MCP, and click Refresh to load the server.
Windsurf
Windsurf uses a global configuration file, mcp_config.json:
- Windows:
%USERPROFILE%\.codeium\windsurf\mcp_config.json - macOS and Linux:
~/.codeium/windsurf/mcp_config.json
STDIO transport (same computer):
{
"mcpServers": {
"j2commerce": {
"command": "php",
"args": [
"/path/to/your/joomla/plugins/system/j2commercemcp/cli/j2commercemcp.php"
],
"env": {
"JOOMLA_API_KEY": "YOUR_TOKEN_HERE"
}
}
}
}
For a remote site, paste the Connect From Anywhere configuration from the panel into the same file. Restart Windsurf after saving. The J2Commerce tools appear in the Cascade panel.
Other MCP Tools
Any tool that speaks MCP can connect. The server uses protocol version 2025-06-18 and also accepts 2025-03-26 and 2024-11-05, so older clients keep working. It offers tools, resources and prompts.
For a STDIO client, use php as the command, the script path as the argument, and JOOMLA_API_KEY in the environment. For an HTTP client, send JSON-RPC 2.0 POST requests with Content-Type: application/json and an Authorization: Bearer header to the endpoint above.
How Changes Are Kept Safe
A tool that changes data runs only when all of these are true:
- Its group is listed under Enabled Tool Groups.
- Its group is ticked under Allow AI to Change (Write) These Groups.
- The signed-in account has the matching J2Commerce permission. Some product changes also need Joomla's Edit permission for J2Commerce.
- For a sign-in through MCP Connect, the assistant was given that access on the consent screen.
Destructive tools ask twice. The first call changes nothing and returns a preview, with a confirmation token.
The assistant must send a second call with that token to apply the change. The token works once, expires after five minutes, and is refused if the arguments differ from the preview.
Every tool call, resource read and prompt request is written to the MCP action log, including the ones that were refused. The MCP dashboard shows tool calls, changes made, refused or failed calls, and the AI clients that connected.
Tool Reference
The plugin has 49 tools in nine groups. Read tools only look.
Write tools change data and need the group's write switch. Write, Confirmed tools also use the two-step confirmation described above.
Products
| Tool | What It Does | Type |
|---|---|---|
j2c_list_products | Lists products with filters for category, price range, manufacturer, product type, visibility or published state. Unpublished products are included unless you filter by state. | Read |
j2c_search_products | Free-text search across name, SKU and descriptions, with optional price and category limits. | Read |
j2c_get_product | Returns one product in full: descriptions, images with alt text, every variant with SKU, price and stock, and the product options. | Read |
j2c_list_inventory | Lists stock on hand for stock-managed variants, optionally only out-of-stock or at or below a threshold. | Read |
j2c_list_product_images | Lists every image on a product, with its position and current alt text. | Read |
j2c_upload_product_image | Attaches an image to a product. Alt text is required. The store chooses the file name and location. Maximum 8 MB; JPG, PNG, GIF, WebP and AVIF. | Write |
j2c_set_product_image_alt | Writes the alt text for an image already on a product. | Write |
j2c_create_product | Creates a simple or downloadable product. It is unpublished unless you pass a state. | Write |
j2c_update_product | Changes fields on a product. Only the fields sent change. Stock and published state are set with their own tools. | Write |
j2c_set_product_state | Publishes, unpublishes, archives or trashes one product. | Write |
j2c_update_variant | Changes price, SKU, dimensions or sale limits on one variant. | Write |
j2c_set_inventory | Sets the stock level of a variant to an exact number. | Write |
j2c_manage_product_tags | Adds an existing Joomla tag to products or removes it. | Write |
j2c_set_custom_field | Sets the value of an existing Joomla custom field on a product. | Write |
j2c_delete_product | Deletes a product with its variants, prices and stock. This cannot be undone. The product's article is not deleted. | Write, Confirmed |
j2c_bulk_update_prices | Raises, lowers or sets the price of many products at once, selected by filter or by ID. The preview shows the old and new price of each product. | Write, Confirmed |
j2c_bulk_set_stock | Sets the same stock level across many products. | Write, Confirmed |
j2c_bulk_publish | Publishes or unpublishes many products at once. | Write, Confirmed |
Orders
| Tool | What It Does | Type |
|---|---|---|
j2c_get_orders | Lists orders, newest first, with filters for status, date range, customer, payment type or total. | Read |
j2c_get_order | Returns one order in full: line items, addresses, tax and shipping, discounts, fees and status history. | Read |
j2c_add_order_note | Adds an internal note to an order. The customer is not emailed and the status does not change. | Write |
j2c_save_tracking | Saves a shipment tracking number on an order. The customer is not emailed. | Write |
j2c_create_draft_order | Builds an order for a customer from variants and quantities. Prices and tax come from the catalog. Nothing is charged and no email is sent. | Write |
j2c_update_order_status | Moves an order to another status. Depending on the status this can email the customer, move stock and grant downloads. | Write, Confirmed |
j2c_cancel_order | Cancels an order with a recorded reason and releases its stock. No money is refunded; refund in your payment gateway. | Write, Confirmed |
Customers
| Tool | What It Does | Type |
|---|---|---|
j2c_get_customers | Lists customers as the store sees them, one row per email with an address on file, with order count and country. | Read |
j2c_get_customer | Returns one registered customer: profile, address book, order count, lifetime spend and first and last order dates. | Read |
j2c_get_customer_report | Ranks registered customers by lifetime spend. | Read |
j2c_update_customer | Corrects the name, contact details or address on a stored customer record. It does not change the Joomla account, login or password. | Write |
Analytics
| Tool | What It Does | Type |
|---|---|---|
j2c_get_store_stats | Revenue, order count, items sold and average order value for a date range. Only completed orders count. | Read |
j2c_get_top_products | Best-selling products for a date range, ranked by quantity or revenue. | Read |
j2c_get_sales_report | Revenue, order count and average order value by day, week, month or year. | Read |
Coupons and Vouchers
| Tool | What It Does | Type |
|---|---|---|
j2c_list_coupons | Lists discount coupons with value, validity window, usage caps and whether each has expired. | Read |
j2c_validate_coupon | Checks a code that exists, is enabled, is inside its dates and meets its minimum spend. It does not check usage caps or product restrictions, so a pass does not promise the discount will apply. The old name j2c_apply_coupon still works. | Read |
j2c_list_vouchers | Lists gift vouchers with value, remaining balance and validity window. Voucher codes are never returned. | Read |
j2c_create_coupon | Creates a discount code. It is enabled on creation unless you say otherwise. | Write |
j2c_update_coupon | Changes a coupon. Only the fields sent change, and the change applies at the next checkout. | Write |
j2c_set_coupon_state | Turns a coupon on or off. | Write |
j2c_create_voucher | Issues a gift voucher for a fixed amount. It is not emailed to anyone. | Write |
j2c_adjust_voucher_balance | Adds to or takes from a voucher's balance, with a reason recorded in its history. Add an order ID to credit the gift card back for a placed order that used it. The credit is capped at what that order is still owed, an amount of 0 credits all of it, and the credit is noted in the order history. The preview shows the amount owed, the capped amount, or that the call would be refused. | Write, Confirmed |
Shipping and Payment
| Tool | What It Does | Type |
|---|---|---|
j2c_get_shipping_methods | Lists the installed shipping plugins and whether each is enabled. Plugin settings are never returned. | Read |
j2c_get_payment_methods | Lists the installed payment plugins and whether each is enabled. Gateway credentials are never returned. | Read |
Reference Data
| Tool | What It Does | Type |
|---|---|---|
j2c_list_countries | Lists countries with ISO codes and enabled state. | Read |
j2c_list_currencies | Lists currencies with code, symbol, exchange rate and number format. | Read |
j2c_list_manufacturers | Lists manufacturers and brands. | Read |
j2c_list_taxprofiles | Lists tax profiles. | Read |
j2c_list_taxrates | Lists tax rates with their percentage and geo zone. | Read |
Store Settings
| Tool | What It Does | Type |
|---|---|---|
j2c_list_store_settings | Lists every store setting an assistant is allowed to change, with its current value. Anything not listed cannot be changed, including currency, tax profiles, payment and shipping configuration and every credential. | Read |
j2c_update_store_setting | Changes one or more of those settings. A change applies to the whole shop immediately, so the preview shows each old and new value first. | Write, Confirmed |
MCP Resources
Resources are read-only reference data an assistant can load. A resource is available only when its tool group is enabled, and the signed-in account needs the matching permission.
| Resource | What It Holds | Group |
|---|---|---|
j2commerce://config | Store configuration: currency, tax handling, catalog and checkout options. Secrets are withheld. | Reference Data |
j2commerce://categories | The full product category tree. | Products |
j2commerce://geozones | Configured geo zones used by shipping and tax rules. | Reference Data |
j2commerce://orders/pending | Orders waiting on you: new, pending or confirmed but not yet shipped. | Orders |
j2commerce://inventory/low-stock | Stock-managed variants at or below their notify level, out-of-stock first. | Products |
j2commerce://order-statuses | Order status IDs and their labels. | Orders |
MCP Prompts
Prompts are ready-made requests an assistant can run. A prompt is available only when every tool group it uses is enabled.
| Prompt | What It Does | Arguments | Groups Needed |
|---|---|---|---|
j2c/analyze-sales | Analyzes sales over a date range: revenue, order volume, average order value and the products behind them. | date_from, date_to (both optional) | Analytics, Orders |
j2c/handle-support-request | Looks up an order and its customer, then drafts a support reply based on the order. | order_id, issue (both required) | Orders, Customers |
j2c/inventory-audit | Produces a low-stock report with suggested reorder quantities. | threshold (optional, default 10) | Products, Analytics |
j2c/write-product-copy | Drafts a product title, description, meta description and image alt text from the product's data. | product_id or category_id (both optional) | Products |
j2c/price-anomaly | Flags pricing and stock outliers. | category_id, days (both optional, days default 90) | Products, Analytics |
j2c/churn-risk | Finds repeat customers who have gone quiet, ranked by what the lapse costs. | days_since_order (optional, default 90) | Customers, Orders |
j2c/seo-audit | Audits product listings for weak or missing titles, descriptions and image alt text. | category_id, limit (both optional, limit default 20) | Products |
Security Considerations
- Keep write access narrow. Leave Allow AI to Change (Write) These Groups empty until you have a task that needs it. Read-only access covers analytics, support lookups and product questions.
- Use an account with limited permissions. A token can do whatever its account can do. Where you can, create a user for the assistant with only the J2Commerce permissions it needs. By default only Super Users may hold API tokens, so change Allowed User Groups on the User - Joomla API Token plugin if you use another group.
- STDIO runs on your machine. The script starts Joomla directly on the computer that runs it. Use it only for tools running on a computer you control, and keep the token out of shared files and version control.
- Protect the HTTP endpoint. A valid token is the only credential it needs. If you connect only from a known network, a server-level IP restriction on the
com_ajaxURL adds another layer. - Reset a token you have shared. Click Reset AI Token on the MCP dashboard to cut off every assistant using the old one.
Verifying the Connection
Test via HTTP
Send a ping from the command line. Replace the token and URL with yours.
curl -X POST \
"https://your-site.com/index.php?option=com_ajax&plugin=j2commercemcp&group=system&format=raw" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_TOKEN_HERE" \
-d '{"jsonrpc":"2.0","method":"ping","id":1}'
A working connection returns a result that is an empty object, with "jsonrpc":"2.0" and "id":1. Without a valid token the endpoint answers with an authentication error.
Test via STDIO
Run the script directly, with your token in the environment:
echo '{"jsonrpc":"2.0","method":"ping","id":1}' | JOOMLA_API_KEY=YOUR_TOKEN_HERE php /path/to/joomla/plugins/system/j2commercemcp/cli/j2commercemcp.php
The reply is the same empty-object result. With no JOOMLA_API_KEY, the script has no account and refuses every request.
Troubleshooting
The AI Tool Reports an Authentication Error
Cause: The request carries no token, or the token or its account is not accepted.
Solution:
- Confirm the token is in the right place:
JOOMLA_API_KEYin a STDIO configuration, or anAuthorization: Bearerheader in an HTTP one. - Open the Connect an AI Assistant panel on the MCP dashboard and read the message at the top. It names what is blocking the account.
- Check that the account is not blocked, has finished activation and any required password reset, and has the API Login permission.
- If you reset the token, paste the new one into every AI tool.
The AI Tool Says a Transport Is Not Enabled
Cause: Allowed Transports does not include the one you are using. An HTTP request gets "HTTP transport not enabled". The STDIO script prints "STDIO transport is not enabled" and exits.
Solution: Open the plugin settings, add HTTP (via com_ajax) or STDIO (CLI for local AI tools) to Allowed Transports, and save.
Tools Are Missing From the AI Tool
Cause: The tool group is not enabled, the account lacks the permission, or the AI tool has not refreshed its list.
Solution:
- Open the plugin settings and confirm the group is ticked under Enabled Tool Groups.
- Confirm the account has the matching J2Commerce permission.
- Reload the MCP servers in your AI tool, or restart it.
A Change Is Refused
Cause: The tool's group is not ticked under Allow AI to Change (Write) These Groups, the account lacks the permission, or an MCP Connect sign-in was not given that access. The refusal reads "Write tools are not enabled for this tool group" or "This assistant was not given permission to do that."
Solution: Tick the group in the plugin settings, check the account's permissions, or reconnect the assistant and approve the access it needs.
A Confirmation Token Is Invalid
Cause: The token is older than five minutes, was already used, or was issued for different arguments.
Solution: Ask the assistant to repeat the first call to get a new preview and token, then confirm that one.
A Bulk Change Is Refused
Cause: The request matches more products than Bulk Change Limit.
Solution: Narrow the request with a category, manufacturer or search term, or raise the limit.
The HTTP Test Returns an HTML Page
Cause: The URL is wrong, or something between you and Joomla is redirecting the request.
Solution:
- Check that the URL matches the HTTP endpoint shown above, including
format=raw. - Check that a firewall or security plugin is not blocking
com_ajax. - Make sure the address does not redirect to another host or to a login page.
The STDIO Script Cannot Start
Cause: The script path is wrong, PHP is not on the path of the AI tool, or the script was not run from the command line.
Solution: Use the full path shown in the Client Configuration panel, and run php -v in a terminal to confirm PHP is available.
Debug Logs Are Empty
Cause: Debug Mode is off.
Solution: Turn on Debug Mode in the plugin settings. Entries are written to plg_system_j2commercemcp.php in your Joomla log folder.
Uninstalling
Go to System -> Manage -> Extensions, search for J2Commerce MCP Server, select it and click Uninstall. Removing the plugin also removes its MCP tables.