Skip to Content
Account
Enter the email address on your account.
Forgot Your Username?
Enter your password.
Forgot Your Password?

Or continue with

J2Commerce 6

J2Commerce MCP Server

22 Min Read

Documentation current for J2Commerce MCP Server v6.5.9. Last checked November 17, 2026.

On This Page

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

  1. Go to System -> Manage -> Plugins.
  2. Search for J2Commerce MCP Server.
  3. 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.

SettingWhat It DoesDefaultOptions
Enabled Tool GroupsThe 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 & PaymentProducts, Orders, Customers, Analytics, Coupons, Shipping & Payment, Reference Data, Store Settings, Other Extensions
Allow AI to Change (Write) These GroupsThe 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 LimitThe 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.1001 to 500
Allowed TransportsHow an assistant may connect. Both need a Joomla API token.STDIO onlyHTTP (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.900 to 3650. 0 keeps the log forever.
Debug ModeWrites connection detail to the Joomla log. Useful when a connection fails.NoYes, 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:

  1. Open the MCP dashboard and find the Connect an AI Assistant panel.
  2. Click Create AI Token. If you already have one, the button reads Reset AI Token, and resetting disconnects every assistant using the old token.
  3. 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:

MessageWhat to Do
The API Authentication - Joomla Token plugin is disabledEnable it in the Plugins manager.
The User - Joomla API Token plugin is disabledEnable it in the Plugins manager so tokens can be created.
This site has no secret configuredCheck the secret value in configuration.php.
Your user group is not allowed to hold API tokensChange the Allowed User Groups setting on the User - Joomla API Token plugin.
You do not have an API token yetClick Create AI Token.
Your API token exists but is switched offTurn it back on from your user profile.
Your account cannot log in to the APIGrant 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 php and sets JOOMLA_API_KEY.
  • Connect From Anywhere: an HTTP setup with the endpoint URL and an Authorization: Bearer header. It is shown only when HTTP is allowed.
  • Older Clients: the same HTTP connection through the free mcp-remote bridge, 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:

  1. Its group is listed under Enabled Tool Groups.
  2. Its group is ticked under Allow AI to Change (Write) These Groups.
  3. The signed-in account has the matching J2Commerce permission. Some product changes also need Joomla's Edit permission for J2Commerce.
  4. 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

ToolWhat It DoesType
j2c_list_productsLists 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_productsFree-text search across name, SKU and descriptions, with optional price and category limits.Read
j2c_get_productReturns one product in full: descriptions, images with alt text, every variant with SKU, price and stock, and the product options.Read
j2c_list_inventoryLists stock on hand for stock-managed variants, optionally only out-of-stock or at or below a threshold.Read
j2c_list_product_imagesLists every image on a product, with its position and current alt text.Read
j2c_upload_product_imageAttaches 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_altWrites the alt text for an image already on a product.Write
j2c_create_productCreates a simple or downloadable product. It is unpublished unless you pass a state.Write
j2c_update_productChanges fields on a product. Only the fields sent change. Stock and published state are set with their own tools.Write
j2c_set_product_statePublishes, unpublishes, archives or trashes one product.Write
j2c_update_variantChanges price, SKU, dimensions or sale limits on one variant.Write
j2c_set_inventorySets the stock level of a variant to an exact number.Write
j2c_manage_product_tagsAdds an existing Joomla tag to products or removes it.Write
j2c_set_custom_fieldSets the value of an existing Joomla custom field on a product.Write
j2c_delete_productDeletes a product with its variants, prices and stock. This cannot be undone. The product's article is not deleted.Write, Confirmed
j2c_bulk_update_pricesRaises, 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_stockSets the same stock level across many products.Write, Confirmed
j2c_bulk_publishPublishes or unpublishes many products at once.Write, Confirmed

Orders

ToolWhat It DoesType
j2c_get_ordersLists orders, newest first, with filters for status, date range, customer, payment type or total.Read
j2c_get_orderReturns one order in full: line items, addresses, tax and shipping, discounts, fees and status history.Read
j2c_add_order_noteAdds an internal note to an order. The customer is not emailed and the status does not change.Write
j2c_save_trackingSaves a shipment tracking number on an order. The customer is not emailed.Write
j2c_create_draft_orderBuilds 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_statusMoves an order to another status. Depending on the status this can email the customer, move stock and grant downloads.Write, Confirmed
j2c_cancel_orderCancels an order with a recorded reason and releases its stock. No money is refunded; refund in your payment gateway.Write, Confirmed

Customers

ToolWhat It DoesType
j2c_get_customersLists customers as the store sees them, one row per email with an address on file, with order count and country.Read
j2c_get_customerReturns one registered customer: profile, address book, order count, lifetime spend and first and last order dates.Read
j2c_get_customer_reportRanks registered customers by lifetime spend.Read
j2c_update_customerCorrects the name, contact details or address on a stored customer record. It does not change the Joomla account, login or password.Write

Analytics

ToolWhat It DoesType
j2c_get_store_statsRevenue, order count, items sold and average order value for a date range. Only completed orders count.Read
j2c_get_top_productsBest-selling products for a date range, ranked by quantity or revenue.Read
j2c_get_sales_reportRevenue, order count and average order value by day, week, month or year.Read

Coupons and Vouchers

ToolWhat It DoesType
j2c_list_couponsLists discount coupons with value, validity window, usage caps and whether each has expired.Read
j2c_validate_couponChecks 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_vouchersLists gift vouchers with value, remaining balance and validity window. Voucher codes are never returned.Read
j2c_create_couponCreates a discount code. It is enabled on creation unless you say otherwise.Write
j2c_update_couponChanges a coupon. Only the fields sent change, and the change applies at the next checkout.Write
j2c_set_coupon_stateTurns a coupon on or off.Write
j2c_create_voucherIssues a gift voucher for a fixed amount. It is not emailed to anyone.Write
j2c_adjust_voucher_balanceAdds 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

ToolWhat It DoesType
j2c_get_shipping_methodsLists the installed shipping plugins and whether each is enabled. Plugin settings are never returned.Read
j2c_get_payment_methodsLists the installed payment plugins and whether each is enabled. Gateway credentials are never returned.Read

Reference Data

ToolWhat It DoesType
j2c_list_countriesLists countries with ISO codes and enabled state.Read
j2c_list_currenciesLists currencies with code, symbol, exchange rate and number format.Read
j2c_list_manufacturersLists manufacturers and brands.Read
j2c_list_taxprofilesLists tax profiles.Read
j2c_list_taxratesLists tax rates with their percentage and geo zone.Read

Store Settings

ToolWhat It DoesType
j2c_list_store_settingsLists 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_settingChanges 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.

ResourceWhat It HoldsGroup
j2commerce://configStore configuration: currency, tax handling, catalog and checkout options. Secrets are withheld.Reference Data
j2commerce://categoriesThe full product category tree.Products
j2commerce://geozonesConfigured geo zones used by shipping and tax rules.Reference Data
j2commerce://orders/pendingOrders waiting on you: new, pending or confirmed but not yet shipped.Orders
j2commerce://inventory/low-stockStock-managed variants at or below their notify level, out-of-stock first.Products
j2commerce://order-statusesOrder 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.

PromptWhat It DoesArgumentsGroups Needed
j2c/analyze-salesAnalyzes 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-requestLooks up an order and its customer, then drafts a support reply based on the order.order_id, issue (both required)Orders, Customers
j2c/inventory-auditProduces a low-stock report with suggested reorder quantities.threshold (optional, default 10)Products, Analytics
j2c/write-product-copyDrafts 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-anomalyFlags pricing and stock outliers.category_id, days (both optional, days default 90)Products, Analytics
j2c/churn-riskFinds repeat customers who have gone quiet, ranked by what the lapse costs.days_since_order (optional, default 90)Customers, Orders
j2c/seo-auditAudits 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_ajax URL 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:

  1. Confirm the token is in the right place: JOOMLA_API_KEY in a STDIO configuration, or an Authorization: Bearer header in an HTTP one.
  2. 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.
  3. Check that the account is not blocked, has finished activation and any required password reset, and has the API Login permission.
  4. 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:

  1. Open the plugin settings and confirm the group is ticked under Enabled Tool Groups.
  2. Confirm the account has the matching J2Commerce permission.
  3. 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:

  1. Check that the URL matches the HTTP endpoint shown above, including format=raw.
  2. Check that a firewall or security plugin is not blocking com_ajax.
  3. 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.

Related Products

MCP Server

Apps J2Commerce

Ask your AI assistant about orders, stock, customers and sales, and get answers from your live J2Commerce store in plain words.

Related Products

MCP Server

Apps J2Commerce

Ask your AI assistant about orders, stock, customers and sales, and get answers from your live J2Commerce store in plain words.

Still stuck? Our team can help.

Back to Top