# Magento 2 / Adobe Commerce MCP Server

A TypeScript MCP server for AI agents that manage Magento 2 / Adobe Commerce back-office tasks.

Use it to build real merchant and operations AI agents. Unlike demo servers that simply expose
API calls, it adds guardrails around Magento operations through bounded inputs, validated
responses, user-approved writes, process-local replay protection, and allowlisted audit logs.

## Features

- **39 admin tools** for orders, fulfillment, customers, products, inventory, quotes, CMS,
  promotions, analytics, and store information.
- **Safe write actions** with user confirmation and a unique operation ID. Reusing the ID with the
  same completed action returns its saved result instead of sending another write to Magento. Writes
  are never retried automatically.
- **Limited API access:** tools use fixed Magento REST routes and accept only known fields and
  filters.
- **Limited data exposure:** page and response sizes are capped, Magento responses are checked, and
  tools return only approved fields as structured JSON.
- **Private configuration:** the Magento URL, store scope, and OAuth credentials stay inside the
  server and cannot be changed by an agent.
- **Works with popular AI stacks** through local stdio or Streamable HTTP, with ready-to-run client
  examples.

See the [tool catalog](docs/tool-catalog.md) for the complete list of 28 read tools and 11 write
tools.

## Production use

This project is a reference implementation and development foundation for purpose-built ecommerce
agents, not a turnkey production platform. Production use requires deployment-specific development,
security review, and testing against the target Adobe Commerce installation and customizations. The
integration must add any identity, data-protection, durability, observability, and operational
controls required by its actual users and environment.

## Quick start

You need Node.js 24, pnpm 10, an Adobe Commerce PaaS site, and OAuth 1.0a integration credentials.

```bash
pnpm install --frozen-lockfile
cp .env.example .env.local
pnpm build
node --env-file=.env.local dist/transports/stdio.js
```

Add your Magento URL, store scope, OAuth credentials, request timeout, and audit path to
`.env.local`. Set `MAGENTO_STORE_SCOPE=default` for the Default Store View or
`MAGENTO_STORE_SCOPE=all` for the global scope. You can also use another configured store view code.
See the [store scope settings](docs/environment.md#store-scope) for details.

Start with one of the included examples:

- [MCP Inspector](docs/inspector.md)
- [Claude Desktop](examples/claude-desktop/README.md)
- [Claude Agent SDK](examples/claude-agent-sdk/README.md)
- [OpenAI Agents SDK](examples/openai-agents-sdk/README.md)
- [LangChain MCP adapter](examples/langchain-mcp-adapter/README.md)
- [Vercel AI SDK](examples/vercel-ai-sdk/README.md)

The example agents enable read tools only. Write tools need an MCP client that supports form
approval.

## Version 0.1 limits and integration responsibilities

This release is a single-merchant admin execution server. Integrations remain responsible for any
surrounding controls required by their deployment.

- **Admin only.** Storefront identity, carts, checkout, payments, consent, and abuse controls belong
  in a separate B2C trust boundary.
- **One merchant per process.** Remote or multi-tenant deployments must add caller authentication,
  authorization, tenant isolation, and credential management outside this server.
- **MCP form approval required.** Clients without form support can use read tools only.
- **Process-local idempotency.** State is not shared across instances or retained after restart;
  deployments requiring durability must add storage and reconciliation.
- **No PII masking or tokenization.** Allowed customer data is returned unchanged; add a trusted
  protection layer if required by the deployment's data policy.
- **Tools only.** Business prompts, workflows, and user experience belong to the agent or
  orchestrator.
- **Local limits only.** The server allows 10 calls per second and 10 active calls per process, not
  distributed or per-user quotas.
- **Local audit only.** Audit records are written to JSON Lines; centralized retention and monitoring
  require an external system.

## Development

```bash
pnpm check
```

Run the optional read-only smoke tests against the site configured in `.env.local`:

```bash
pnpm test:live
```

## Documentation

- [Deployment and integration](docs/deployment.md)
- [Security model](docs/security.md)
- [Environment settings](docs/environment.md)
- [Tool catalog](docs/tool-catalog.md)
- [Error handling](docs/error-handling.md)
- [Client examples](examples/README.md)

## License

[MIT](LICENSE). This is an independent open-source project and is not an official Adobe product.