README

Adwise_Mcp

A lightweight Magento MCP (Model Context Protocol) server.

Installation

composer require adwise/magento2-mcp
bin/magento module:enable Adwise_Mcp
bin/magento setup:upgrade

stdio transport

From the Magento project root:

vendor/bin/magento-mcp

For a local MCP client, configure the command as ddev with arguments:

{
  "mcpServers": {
    "magento": {
      "command": "ddev",
      "args": ["exec", "php", "vendor/bin/magento-mcp"]
    }
  }
}

SSE transport

The server is also available over SSE:

GET  /mcp/sse
POST /mcp/message?session=<session-id-from-sse-endpoint-event>

Authentication uses bearer tokens. Send the token with either:

Authorization: Bearer <admin-or-integration-token>

or, for clients that cannot set SSE headers:

/mcp/sse?access_token=<token>

The token owner must have the ACL resource Adwise_Mcp::mcp (System > Adwise Magento MCP). Integration tokens also need this resource granted in the integration API permissions.

MCP OAuth discovery and browser login

The SSE endpoint returns a WWW-Authenticate header with a protected resource metadata URL when no token is supplied. Metadata endpoints:

GET  /.well-known/oauth-protected-resource
GET  /.well-known/oauth-authorization-server
GET  /mcp/oauth/protectedresource
GET  /mcp/oauth/metadata
POST /mcp/oauth/register
POST /mcp/oauth/token

The OAuth authorization endpoint returned by metadata is an adminhtml URL. MCP clients can open it in the browser. Magento will require admin login and the Adwise_Mcp::mcp ACL, then redirect back with an authorization code. The token endpoint exchanges the code for a Magento admin bearer token. Authorization code + PKCE (S256 or plain) is supported.

Included tools

• magento_info - Magento name, edition, version, and mode.
• module_status - List modules or inspect a single module.
• config_get - Read config values by path and scope.
• cache - Read cache status, clean cache, or flush cache.
• indexer_status - List indexer statuses or inspect a single indexer.

Add a tool

1. Create a class implementing Adwise\Mcp\Api\ToolInterface.
2. Register it in etc/di.xml under Adwise\Mcp\Model\Mcp\JsonRpcServer's tools argument.
3. Run bin/magento setup:di:compile if generated DI is in use.

Tool results can return any JSON-serializable data. The server wraps that data in an MCP text content response.