{"id":49777617,"url":"https://github.com/magebitcom/magento2-mcp-module","last_synced_at":"2026-05-11T16:01:45.929Z","repository":{"id":356026793,"uuid":"1206749337","full_name":"magebitcom/magento2-mcp-module","owner":"magebitcom","description":"Extensible MCP module for Magento2 - Turn your store into an MCP server","archived":false,"fork":false,"pushed_at":"2026-05-06T08:49:35.000Z","size":313,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-06T10:44:11.596Z","etag":null,"topics":["adobe","adobe-commerce","ai","magento2","magento2-extension","magento2-module","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/magebitcom.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-10T08:09:12.000Z","updated_at":"2026-05-06T08:49:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/magebitcom/magento2-mcp-module","commit_stats":null,"previous_names":["magebitcom/magento2-mcp-module"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/magebitcom/magento2-mcp-module","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magebitcom%2Fmagento2-mcp-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magebitcom%2Fmagento2-mcp-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magebitcom%2Fmagento2-mcp-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magebitcom%2Fmagento2-mcp-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/magebitcom","download_url":"https://codeload.github.com/magebitcom/magento2-mcp-module/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/magebitcom%2Fmagento2-mcp-module/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32902254,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-10T13:40:02.631Z","status":"online","status_checked_at":"2026-05-11T02:00:05.975Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adobe","adobe-commerce","ai","magento2","magento2-extension","magento2-module","mcp-server"],"created_at":"2026-05-11T16:01:00.960Z","updated_at":"2026-05-11T16:01:45.909Z","avatar_url":"https://github.com/magebitcom.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/header.svg\" alt=\"Sample MCP session: an operator asks why a customer's order hasn't arrived; the AI calls three MCP tools and reports the order status, shipment progress, and customer history.\" width=\"100%\"\u003e\n\u003c/p\u003e\n\n# Magento 2 MCP module\n\nExtensible [Model Context Protocol](https://modelcontextprotocol.io/specification/2025-06-18) 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.\n\nThe 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.\n\n## Contents\n\n- [What the base module gives you](#what-the-base-module-gives-you)\n- [Installation](#installation)\n- [Sub-modules](#sub-modules)\n  - [Order module — `Magebit_McpOrderTools`](#order-module--magebit_mcpordertools)\n  - [Catalog module — `Magebit_McpCatalogTools`](#catalog-module--magebit_mcpcatalogtools)\n  - [Customer module — `Magebit_McpCustomerTools`](#customer-module--magebit_mcpcustomertools)\n  - [CMS module — `Magebit_McpCmsTools`](#cms-module--magebit_mcpcmstools)\n  - [Marketing module — `Magebit_McpMarketingTools`](#marketing-module--magebit_mcpmarketingtools)\n  - [Report module — `Magebit_McpReportTools`](#report-module--magebit_mcpreporttools)\n- [Setup](#setup)\n- [Connecting an AI agent](#connecting-an-ai-agent)\n  - [Bearer token](#bearer-token)\n  - [OAuth 2.1](#oauth-21)\n- [Security](#security)\n- [Extending](#extending)\n- [Contributing](#contributing)\n\n## What the base module gives you\n\n- A `POST /mcp` JSON-RPC endpoint with bearer-token and OAuth 2.1 authentication\n- Per-tool admin-role ACL and a two-layer write kill-switch\n- A PII-redacting audit log with configurable retention\n- Per-(admin, tool) rate limiting\n- An origin allowlist with sensible defaults for major AI clients\n- Core tools for cache types, indexers, store views, system configuration values and admin notifications\n- MCP prompt support (see examples in [Prompt/System](Prompt/System/) directory)\n\n## Installation\n\n```bash\ncomposer require magebitcom/magento2-mcp-module\nbin/magento module:enable Magebit_Mcp\nbin/magento setup:upgrade\n```\n\n## Sub-modules\n\nEach 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:\n\n```bash\nbin/magento module:enable Magebit_Mcp\u003cName\u003eTools\nbin/magento setup:upgrade\n```\n\n### Order module — [`Magebit_McpOrderTools`](https://github.com/magebitcom/magento2-mcp-order-tools)\n- Read and search orders, invoices, shipments, payments, order comments and credit memos\n- Create invoices, shipments, shipment tracks, credit memos and order comments\n- Cancel, hold or unhold orders\n\n```bash\ncomposer require magebitcom/magento2-mcp-order-tools\n```\n\n### Catalog module — [`Magebit_McpCatalogTools`](https://github.com/magebitcom/magento2-mcp-catalog-tools)\n- Read and search products and categories\n- Create, update or delete products\n- Create, update or delete categories\n\n```bash\ncomposer require magebitcom/magento2-mcp-catalog-tools\n```\n\n### Customer module — [`Magebit_McpCustomerTools`](https://github.com/magebitcom/magento2-mcp-customer-tools)\n- Read or search customers, addresses and customer groups\n- Fetch customer confirmation status\n- Create, update or delete customers and addresses\n- Trigger password reset or resend confirmation\n\n```bash\ncomposer require magebitcom/magento2-mcp-customer-tools\n```\n\n### CMS module — [`Magebit_McpCmsTools`](https://github.com/magebitcom/magento2-mcp-cms-tools)\n- Read or search CMS pages and blocks\n- Create, update or delete CMS pages and blocks\n\n```bash\ncomposer require magebitcom/magento2-mcp-cms-tools\n```\n\n### Marketing module — [`Magebit_McpMarketingTools`](https://github.com/magebitcom/magento2-mcp-marketing-tools)\n- Read or search catalog rules, cart rules and coupons\n- Delete, toggle and apply catalog and cart rules\n- Generate or delete coupon codes\n\n```bash\ncomposer require magebitcom/magento2-mcp-marketing-tools\n```\n\n### Report module — [`Magebit_McpReportTools`](https://github.com/magebitcom/magento2-mcp-report-tools)\n- Cart reports (products in cart, abandoned carts)\n- Popular search queries and newsletter problems (bounces, send failures)\n- Product reviews, review counts and average ratings\n- Aggregated sales reports for orders, tax, invoices, shipments, refunds and coupons\n- Customer reports (orders, totals, new customers, online visitors)\n- Product reports (most viewed, bestsellers, low-stock, qty ordered, downloads)\n- Dashboard summary (lifetime sales, average order, revenue for a period, recent orders, top search terms, top bestsellers)\n- Refresh sales/customer/review statistics\n\n```bash\ncomposer require magebitcom/magento2-mcp-report-tools\n```\n\n## Setup\n\nConfiguration lives under **Stores → Configuration → Magebit → MCP Server**. Defaults are sensible for development; review every section before going to production.\n\n| Setting | Default | Notes |\n|---|---|---|\n| **General → Enable MCP Server** | Yes | Master kill-switch. When off, every request returns HTTP 503 before authentication runs. |\n| **General → Server Name** | `Magento MCP` | Advertised to MCP clients during the `initialize` handshake. |\n| **General → Server Description** | empty | Optional free-text hint advertised alongside the server name. |\n| **General → Allow Write Tools** | Yes | Global toggle. A token's per-row write flag is only honoured when this is on. |\n| **Security → Allowed Origins** | localhost + Claude, ChatGPT, Gemini, Copilot, Grok and Perplexity | One origin per line. Trailing `*` is allowed. Tighten for production. |\n| **Audit Log → Retention (days)** | `90` | Older rows are purged by the `magebit_mcp_audit_purge` cron. `0` disables purging. |\n| **Rate Limiting → Enabled** | No | Caps `tools/call` requests per (admin, tool) per minute. Recommended for production. |\n| **Rate Limiting → Requests Per Minute** | `60` | Used when rate limiting is enabled. |\n| **OAuth 2.1 → Access Token Lifetime** | `3600` (1 hour) | |\n| **OAuth 2.1 → Refresh Token Lifetime (days)** | `30` | |\n| **OAuth 2.1 → Authorization Code Lifetime** | `60` (seconds) | Increase only for debugging. |\n\nFour separate admin-role permissions gate the module so a token-manager role need not see the audit log and vice versa:\n\n- `Magebit_Mcp::mcp_tokens` — create, list, revoke and delete bearer tokens\n- `Magebit_Mcp::mcp_oauth_clients` — manage OAuth clients\n- `Magebit_Mcp::mcp_audit` — view the audit log\n- `Magebit_Mcp::config` — change settings under *Stores → Configuration → Magebit → MCP Server*\n\nEach 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.\n\n## Connecting an AI agent\n\nTwo 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.\n\n### Bearer token\n\nMint a token from the CLI (or from **System → MCP → Connections** in the admin):\n\n```bash\nbin/magento magebit:mcp:token:create \\\n  --admin-user \u003cusername\u003e \\\n  --name \"\u003clabel\u003e\" \\\n  [--allow-writes] \\\n  [--expires \"+30 days\"] \\\n  [-s \u003ctool.name\u003e] [-s \u003ctool.name\u003e]\n```\n\nThe plaintext is printed once and is never recoverable afterwards — store it securely. Manage tokens with:\n\n```bash\nbin/magento magebit:mcp:token:list [-u \u003cusername\u003e]\nbin/magento magebit:mcp:token:revoke \u003cid\u003e   # day-to-day; preserves the audit trail\nbin/magento magebit:mcp:token:delete \u003cid\u003e   # hard-delete\n```\n\nConfigure your MCP client with:\n\n| Setting | Value |\n|---|---|\n| URL | `https://\u003cyour-store\u003e/mcp` |\n| Authorization header | `Bearer \u003ctoken\u003e` |\n\n### OAuth 2.1\n\nManage OAuth clients under **System → MCP → OAuth Clients**. The module exposes:\n\n| Endpoint | Purpose |\n|---|---|\n| `GET /.well-known/oauth-authorization-server` | Authorization-server metadata (RFC 8414). |\n| `GET /.well-known/oauth-protected-resource` | Protected-resource metadata (RFC 9728). |\n| `GET\\|POST /mcp/oauth/authorize` | Interactive consent screen. Requires admin sign-in. |\n| `POST /mcp/oauth/token` | Token endpoint (`authorization_code` and `refresh_token` grants). |\n\nTwo scopes are advertised:\n\n- `mcp:read` — invoke read-only tools\n- `mcp:write` — also invoke write tools (still subject to the global write toggle)\n\nEach 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.\n\n## Security\n\n- **Two authentication paths.** Bearer tokens issued by an admin, and OAuth 2.1 with mandatory PKCE.\n- **Origin allowlist.** Configurable; defaults cover only loopback and the major AI surfaces. Tighten for production.\n- **Per-tool admin-role ACL.** Every tool resolves through Magento's standard role permissions — MCP can never do what the admin UI would forbid.\n- **Two-layer write gating.** Write tools require the global *Allow write tools* toggle *and* a per-token (or per-OAuth-scope) write flag.\n- **Confirmation hint for destructive tools.** Write tools may flag themselves as requiring confirmation; clients that support it (e.g. Claude Desktop) prompt the operator.\n- **Per-(admin, tool) rate limiter.** Off by default; recommended for production.\n- **Audit log.** Every request is recorded — even unauthenticated attempts. Argument values are PII-redacted before storage.\n- **Separated admin permissions.** Token management, OAuth-client management, audit-log viewing and module configuration are four distinct ACLs.\n\nIf you discover a security issue, please report it privately to [info@magebit.com](mailto:info@magebit.com) rather than opening a public issue.\n\n## Extending\n\nWrite your own tools and prompts by implementing `Magebit\\Mcp\\Api\\ToolInterface` (or `PromptInterface`) and registering them via `di.xml`. The six sub-modules listed above are full worked examples.\n\nThe contract surface is:\n\n1. 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`).\n2. 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_]*)+$`.\n3. 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.\n4. Run `bin/magento magebit:mcp:tools:validate-acl` to confirm every tool's ACL resource resolves.\n\nSee [docs/EXTENDING.md](docs/EXTENDING.md) for the full contract, the schema-builder DSL, schema presets, the field-resolver pattern, lifecycle events, and a complete worked example.\n\n## Contributing\n\nFound a bug, have a feature suggestion or want to help? Contributions are very welcome — open an issue or pull request on GitHub.\n\n---\n\n![magebit (1)](https://github.com/user-attachments/assets/cdc904ce-e839-40a0-a86f-792f7ab7961f)\n\n*Have questions or need help? Contact us at info@magebit.com*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagebitcom%2Fmagento2-mcp-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmagebitcom%2Fmagento2-mcp-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmagebitcom%2Fmagento2-mcp-module/lists"}