Magento 2 MCP module

Extensible Model Context Protocol server for Magento 2. Connect your store to any MCP-compatible AI agent — read and mutate customer, product, CMS or sales data, fetch reports, manage configuration, and more.

The base module ships the transport, authentication, ACL, audit log, and tool registry, plus a small set of system tools for inspecting and refreshing the store. Domain-specific functionality lives in optional sub-modules listed below — you can also write your own.

Contents

• What the base module gives you
• Quick start
• Installation
• Sub-modules
  • Order module — Magebit_McpOrderTools
  • Catalog module — Magebit_McpCatalogTools
  • Customer module — Magebit_McpCustomerTools
  • Inventory module — Magebit_McpInventoryTools
  • CMS module — Magebit_McpCmsTools
  • Marketing module — Magebit_McpMarketingTools
  • Tax and currency module — Magebit_McpTaxTools
  • Report module — Magebit_McpReportTools
  • Google Analytics module — Magebit_McpGoogleAnalyticsTools
  • Database module — Magebit_McpDbTools
• Setup
• Managing tools
• Configuration writing
• Connecting an AI agent
  • Bearer token
  • OAuth 2.1
• Security
• Extending
• Contributing

What the base module gives you

• A POST /mcp JSON-RPC endpoint with bearer-token and OAuth 2.1 authentication
• Per-tool admin-role ACL and a two-layer write kill-switch
• A PII-redacting audit log with configurable retention
• Per-(admin, tool) rate limiting
• An origin allowlist with sensible defaults for major AI clients
• Core tools for the authenticated identity, cache types, indexers, store views, installed modules (system.module.list, for checking what the store actually supports before picking a tool), system configuration values and admin notifications
• Configuration writing (system.config.set), off by default and allowlist-only — see Configuration writing
• Scheduled-job diagnostics (system.cron.status), so the AI can answer "why didn't that run automatically?" — per-job last success/error, stuck-job detection, and per-group retention. Absent run history is not evidence a job never ran: Magento prunes successful cron rows aggressively (60 minutes by default), so no_run_history is normal for most of the day on any job that doesn't run every few minutes
• Read-only log diagnostics (system.log.list / system.log.tail / system.log.grep), so the AI can read var/log without shell access — basename-only, .log files only. Every read is bounded (line and match caps, a total byte budget) and never loads a whole file. Log lines routinely contain customer PII, tokens, or credentials, so grant the underlying tool ACLs to admin roles accordingly
• MCP prompt support (see examples in Prompt/System directory)

Quick start

The fastest path from composer require to a connected AI is the interactive Quick Setup guide — pick which AI you're using (Claude, ChatGPT, Cursor, Claude Code, or anything else MCP-compatible) and follow the per-client steps with copy-paste snippets and admin-screen screenshots.

Not connecting? The Connection Checker probes your store's MCP endpoints from the browser and flags redirects, unreachable hosts and base-URL mismatches; the MCP Inspector guide walks you through verifying the OAuth sign-in and bearer-token access end to end.

For the long-form reference — every admin setting, the OAuth and bearer-token flows in detail, and the full tool catalog — see the Wiki.

Installation

composer require magebitcom/magento2-mcp-module
bin/magento module:enable Magebit_Mcp
bin/magento setup:upgrade

That gives you the server and its system.* tools, and nothing else.

Installing everything at once

To get the server plus the catalog, CMS, customer, inventory, marketing, order, report and tax modules in one step, require the suite meta-package instead of picking sub-modules by hand:

composer require magebitcom/magento2-mcp-suite
bin/magento setup:upgrade

The suite contains no code of its own — only a dependency list — so what it installs is nine ordinary Magento modules. That means you stop choosing your tool surface at composer require time and start choosing it in app/etc/config.php, where 1 is enabled and 0 is disabled:

'modules' => [
    // ...
    'Magebit_Mcp' => 1,
    'Magebit_McpCatalogTools' => 1,
    'Magebit_McpCmsTools' => 1,
    'Magebit_McpCustomerTools' => 1,
    'Magebit_McpInventoryTools' => 1,
    'Magebit_McpMarketingTools' => 1,
    'Magebit_McpOrderTools' => 1,
    'Magebit_McpReportTools' => 0,
    'Magebit_McpTaxTools' => 0,
],

bin/magento module:disable Magebit_McpReportTools edits the same file. Because config.php is committed, this is how you give each environment a different tool surface from one install — full write access on staging, a narrower set in production.

Two caveats worth knowing:

• setup:upgrade enables modules it has not seen before. Adding the suite to an existing store lands all nine as => 1. If some should be off, disable them in the same deploy, before the store serves traffic.
• Disabling a module is a blunt instrument. To keep one installed but hide individual tools, use System → MCP → Tools in the admin, which toggles a single tool at a time behind its own ACL resource.

The Google Analytics and database modules are deliberately not in the suite — the first needs a Google login and pulls in the Google SDKs, the second grants bulk database reads. Both are listed below and are one composer require away.

Sub-modules

Each sub-module is published independently and depends on Magebit_Mcp. Install only the ones you need. After every composer require below, enable and rebuild Magento with:

bin/magento module:enable Magebit_Mcp<Name>Tools
bin/magento setup:upgrade

Every tool module — ours and third-party ones — carries the magebit-mcp-tools GitHub topic, so browsing that topic lists the full ecosystem, including modules not documented here.

Order module — Magebit_McpOrderTools

• Read and search orders, invoices, shipments, payments, order comments and credit memos
• Create invoices, shipments, shipment tracks, credit memos and order comments
• Cancel, hold or unhold orders

composer require magebitcom/magento2-mcp-order-tools

Catalog module — Magebit_McpCatalogTools

• Read and search products and categories
• Create, update or delete products
• Create, update or delete categories
• Set stock levels in bulk, and upload or manage product images

composer require magebitcom/magento2-mcp-catalog-tools

Inventory module — Magebit_McpInventoryTools

• Read sources, stocks and per-source quantities
• Report salable quantity and the reservations behind it
• Set or unassign quantities per (SKU, source) in bulk
• Manage sources, stocks, source links and website assignments
• Bulk assign, unassign and transfer inventory between sources

Requires Magento's Multi-Source Inventory. For a single-stock store,
catalog.product.stock.set in the catalog module is enough.

composer require magebitcom/magento2-mcp-inventory-tools

Customer module — Magebit_McpCustomerTools

• Read or search customers, addresses and customer groups
• Fetch customer confirmation status
• Create, update or delete customers and addresses
• Trigger password reset or resend confirmation

composer require magebitcom/magento2-mcp-customer-tools

CMS module — Magebit_McpCmsTools

• Read or search CMS pages and blocks
• Create, update or delete CMS pages and blocks

composer require magebitcom/magento2-mcp-cms-tools

Marketing module — Magebit_McpMarketingTools

• Read or search catalog rules, cart rules and coupons
• Delete, toggle and apply catalog and cart rules
• Generate or delete coupon codes

composer require magebitcom/magento2-mcp-marketing-tools

Tax and currency module — Magebit_McpTaxTools

• Read or search tax rates, tax rules and tax classes
• Create, update or delete tax rates, rules and classes
• Read currency configuration (base, default and allowed currencies)
• Set currency exchange rates manually or import them from the configured service

composer require magebitcom/magento2-mcp-tax-tools

Report module — Magebit_McpReportTools

• Cart reports (products in cart, abandoned carts)
• Popular search queries and newsletter problems (bounces, send failures)
• Product reviews, review counts and average ratings
• Aggregated sales reports for orders, tax, invoices, shipments, refunds and coupons
• Customer reports (orders, totals, new customers, online visitors)
• Product reports (most viewed, bestsellers, low-stock, qty ordered, downloads)
• Dashboard summary (lifetime sales, average order, revenue for a period, recent orders, top search terms, top bestsellers)
• Refresh sales/customer/review statistics

composer require magebitcom/magento2-mcp-report-tools

Google Analytics module — Magebit_McpGoogleAnalyticsTools

• List Google Analytics accounts and GA4 properties for the connected Google account
• Inspect GA4 property details (name, currency, timezone, industry) and linked Google Ads accounts
• List a property's custom dimensions and metrics
• Run GA4 Data API reports — core, real-time (last 30 minutes) and funnel
• Read-only; authenticates to Google via OAuth with an encrypted refresh token

composer require magebitcom/magento2-mcp-google-analytics-tools

Database module — Magebit_McpDbTools

⚠️ Not a default install. This module hands an MCP client bulk read access to your production database. Read its README in full before enabling it.

• One tool, db.query: a single guarded, read-only SELECT returned as JSON
• Off by default, and allowlist-only — with no tables allowlisted it refuses every query
• Credentials, sessions and config secrets are in a protected set that no allowlist entry can re-open
• Every table a statement names must be mapped to the admin ACL resource that reads it, so raw SQL reads no more than its caller could already reach in the admin UI; an unmapped table is refused

A read-only query is still bulk data extraction: the guard bounds the shape of a query and the tables it may name, not how sensitive the data behind them is. Allowlisting sales_order means the token holder can read every customer name, e-mail and phone number in the store — a processing decision under GDPR-style regimes, not a convenience one. Prefer the domain modules above, which expose the same data with a narrow ACL per tool and named arguments instead of an opaque SQL string; reach for db.query only when a question cannot be answered any other way.

composer require magebitcom/magento2-mcp-db-tools

Setup

Configuration lives under Stores → Configuration → Magebit → MCP Server. Defaults are sensible for development; review every section before going to production.

Five separate admin-role permissions gate the module so a token-manager role need not see the audit log and vice versa:

• Magebit_Mcp::mcp_tokens — create, list, revoke and delete bearer tokens
• Magebit_Mcp::mcp_oauth_clients — manage OAuth clients
• Magebit_Mcp::mcp_audit — view the audit log
• Magebit_Mcp::mcp_tool_management — enable and disable individual tools, see Managing tools
• Magebit_Mcp::config — change settings under Stores → Configuration → Magebit → MCP Server

Each MCP tool is also gated by its own admin-role permission under Magebit_Mcp::tools. Restrict admins to the subset they should be able to drive.

Managing tools

System → MCP → Tools lists every registered tool with an Enable/Disable action, gated by the Magebit_Mcp::mcp_tool_management permission — separate from the per-tool ACLs under Magebit_Mcp::tools, so a role can manage which tools are available without being able to drive any of them itself.

Disabling a tool is indistinguishable on the wire from the tool never having existed: it drops out of tools/list, and a tools/call for it returns the same -32010 TOOL_NOT_FOUND error, with the same message, that an unregistered tool name would produce. This is deliberate — probing the tool surface tells a client nothing about which tools exist but are switched off. The guarantee covers that surface only: a prompt body that names a tool goes on naming it whether or not the tool is currently disabled.

The disabled set is stored as a newline-separated list of tool names at magebit_mcp/tools/disabled (default/global scope). It is written only from the Tools page, not exposed as a field under Stores → Configuration, and system.config.get refuses to read it back — the whole magebit_mcp/* section is off limits to the config reader, just as it is to the writer.

bin/magento magebit:mcp:tools:list deliberately keeps listing disabled tools: it reports what the installed modules register, and the switch governs what the MCP endpoint serves, not what an operator on the command line can see.

Configuration writing

system.config.set writes a single store-configuration value. It is the only tool that can change how the store behaves without touching the catalog, so it is gated more tightly than anything else in the module.

Both write layers still apply first. Like every write tool it needs General → Allow Write Tools and the calling token's own write flag, plus the Magebit_Mcp::tool_system_config_set ACL on the admin role behind the token. On top of that:

The write itself goes through Magento's admin save path, so the field's backend model, validation and cache invalidation run exactly as they would in Stores → Configuration. The result and the audit row both carry the previous value, which is the only undo trail a config change gets. As in the admin UI, Magento commits the row before it dispatches the section's admin_system_config_changed_section_* observers, so an observer that fails is reported as a tool error against a value that was in fact written.

The protected set is admin/*, payment/* (including Magento_Paypal's payment_<country> alias sections), web/secure/*, web/unsecure/*, system/*, dev/*, oauth/* and magebit_mcp/*. It lives in di.xml, not in store configuration, so weakening it takes filesystem write access plus bin/magento setup:di:compile — neither an admin session nor the MCP surface itself can widen it. magebit_mcp/* is on the list for exactly that reason: without it the tool would be a one-call privilege escalation, able to add paths to its own allowlist or flip Allow Write Tools.

Password, encrypted and obscured fields are refused as well, as are file- and image-upload fields (a plain value would be discarded by the field's backend model while the save still reported success), paths whose system.xml field stores its value somewhere else (<config_path>) and paths pinned in app/etc/env.php or by a CONFIG__* environment variable — the last two would report a change Magento silently skipped.

Not everything in core_config_data is writable, by design. A stock install declares roughly 11,000 field paths and the gates above refuse the great majority of them, whatever the allowlist says: most store their value under a different <config_path>, are not declared in system.xml at all, or are a password, an obscured value or a file upload. Allowlisting such a path does not help — the refusal is not the allowlist's. The most common surprise is the design/* family (design/header/logo_alt, design/head/default_title, …): those are Design Configuration entries under Content → Design → Configuration, not system.xml fields, so they are refused as undeclared. Use the admin UI for them.

Reading is a separate, wider surface. system.config.get returns the effective value, merged from config.xml module defaults, so a path with no core_config_data row still reports a value. Reading the same path straight from the database, or with bin/magento config:show, returns nothing — that difference is expected and does not mean the setting is unset.

Connecting an AI agent

Two authentication paths. Bearer tokens are simplest; OAuth 2.1 is the right choice for hosted MCP clients (Claude, ChatGPT) that ask the operator to consent.

Bearer token

Mint a token from the CLI (or from System → MCP → Connections in the admin):

bin/magento magebit:mcp:token:create \
  --admin-user <username> \
  --name "<label>" \
  [--allow-writes] \
  [--expires "+30 days"] \
  [-s <tool.name>] [-s <tool.name>]

The plaintext is printed once and is never recoverable afterwards — store it securely. Manage tokens with:

bin/magento magebit:mcp:token:list [-u <username>]
bin/magento magebit:mcp:token:revoke <id>   # day-to-day; preserves the audit trail
bin/magento magebit:mcp:token:delete <id>   # hard-delete

Configure your MCP client with:

OAuth 2.1

Manage OAuth clients under System → MCP → OAuth Clients. The module exposes:

Two scopes are advertised:

• mcp:read — invoke read-only tools
• mcp:write — also invoke write tools (still subject to the global write toggle)

Each OAuth client has its own scope cap and the consenting admin can narrow further at the consent screen. OAuth-issued tokens land in the same Connections list as bearer tokens, so you manage and revoke them in one place.

Security

• Two authentication paths. Bearer tokens issued by an admin, and OAuth 2.1 with mandatory PKCE.
• Origin allowlist. Configurable; defaults cover only loopback and the major AI surfaces. Tighten for production.
• Per-tool admin-role ACL. Every tool resolves through Magento's standard role permissions — MCP can never do what the admin UI would forbid.
• Two-layer write gating. Write tools require the global Allow write tools toggle and a per-token (or per-OAuth-scope) write flag.
• Allowlisted configuration writing. system.config.set is off by default and can only write the exact paths an admin lists; a protected set defined in code — including the module's own settings — is refused whatever the allowlist says. See Configuration writing.
• No raw SQL in the base module. db.query ships only in the separately installed Magebit_McpDbTools, which is off by default and allowlist-only. Nothing in the base module or the domain sub-modules accepts an SQL string.
• Confirmation hint for destructive tools. Write tools may flag themselves as requiring confirmation; clients that support it (e.g. Claude Desktop) prompt the operator.
• Per-(admin, tool) rate limiter. Off by default; recommended for production.
• Audit log. Every request is recorded — even unauthenticated attempts. Argument values are PII-redacted before storage.
• Separated admin permissions. Token management, OAuth-client management, audit-log viewing, tool management and module configuration are five distinct ACLs.

If you discover a security issue, please report it privately to [email protected] rather than opening a public issue.

Extending

Write your own tools and prompts by implementing Magebit\Mcp\Api\ToolInterface (or PromptInterface) and registering them via di.xml. The sub-modules listed above are full worked examples.

The contract surface is:

1. Implement Magebit\Mcp\Api\ToolInterface and declare an ACL resource for the tool. By convention, dots in the tool name become underscores in the ACL id (catalog.product.get → Vendor_Module::mcp_tool_catalog_product_get).
2. Register the tool in di.xml under Magebit\Mcp\Model\Tool\ToolRegistry. The DI key must match the tool's getName() and conform to ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$.
3. For write tools that wrap a Magento service contract, optionally implement Magebit\Mcp\Api\UnderlyingAclAwareInterface so the dispatcher also enforces the equivalent admin-UI permission. tools/list applies the same check, so a role that lacks the underlying permission is never offered the tool.
4. Run bin/magento magebit:mcp:tools:validate-acl to confirm every tool's ACL resource resolves. It also warns about underlying resources that do not resolve on this install — those tools stay hidden from tools/list for every role.

Publishing your module? Add the magebit-mcp-tools topic to its GitHub repository so it turns up alongside the rest of the ecosystem.

See docs/EXTENDING.md for the full contract, the schema-builder DSL, schema presets, the field-resolver pattern, lifecycle events, and a complete worked example.

Contributing

Found a bug, have a feature suggestion or want to help? Contributions are very welcome — open an issue or pull request on GitHub.

Magebit - Full-service e-commerce agency

magebit.com