{
  "markdown": "# mcp-server-woocommerce\n\n[![CI](https://github.com/AmitGurbani/mcp-server-woocommerce/actions/workflows/ci.yml/badge.svg)](https://github.com/AmitGurbani/mcp-server-woocommerce/actions/workflows/ci.yml)\n[![npm](https://img.shields.io/npm/v/@amitgurbani/mcp-server-woocommerce)](https://www.npmjs.com/package/@amitgurbani/mcp-server-woocommerce)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org)\n\nMCP server for managing WooCommerce stores through AI assistants like Claude. Provides 101 tools covering products, orders, customers, coupons, shipping, taxes, webhooks, settings, reports, and more.\n\n## Quick Start\n\n**1. Get WooCommerce API keys**\n\nIn your WordPress admin: **WooCommerce > Settings > Advanced > REST API > Add key** with Read/Write permissions.\n\n**2. Add to your AI tool**\n\nNo install needed — runs directly via `npx`:\n\n<details open>\n<summary><strong>Claude Code</strong></summary>\n\nAdd to your project's `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"woocommerce\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@amitgurbani/mcp-server-woocommerce\"],\n      \"env\": {\n        \"WORDPRESS_SITE_URL\": \"https://store.example.com\",\n        \"WOOCOMMERCE_CONSUMER_KEY\": \"ck_your_key\",\n        \"WOOCOMMERCE_CONSUMER_SECRET\": \"cs_your_secret\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"woocommerce\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@amitgurbani/mcp-server-woocommerce\"],\n      \"env\": {\n        \"WORDPRESS_SITE_URL\": \"https://store.example.com\",\n        \"WOOCOMMERCE_CONSUMER_KEY\": \"ck_your_key\",\n        \"WOOCOMMERCE_CONSUMER_SECRET\": \"cs_your_secret\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\n[Install in Cursor](cursor://settings/mcp/add?name=woocommerce&type=stdio&command=npx&args=-y,@amitgurbani/mcp-server-woocommerce) (one-click) or add to `.cursor/mcp.json` in your project root:\n\n```json\n{\n  \"mcpServers\": {\n    \"woocommerce\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@amitgurbani/mcp-server-woocommerce\"],\n      \"env\": {\n        \"WORDPRESS_SITE_URL\": \"https://store.example.com\",\n        \"WOOCOMMERCE_CONSUMER_KEY\": \"ck_your_key\",\n        \"WOOCOMMERCE_CONSUMER_SECRET\": \"cs_your_secret\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n**4. Start using it** — ask your AI assistant things like:\n\n> \"List all products that are out of stock\"\n> \"Create a 10% off coupon for orders over $50\"\n> \"Show me this week's sales report\"\n\n## Features\n\n- **Full store management** — CRUD operations for products, categories, tags, brands, orders, customers, and coupons\n- **Product taxonomy** — attributes, attribute terms, and variations with batch support\n- **Shipping** — zones, zone methods, and shipping classes\n- **Taxes** — tax rates and tax classes\n- **Webhooks** — create, manage, and monitor webhook subscriptions\n- **Settings** — read and update store configuration\n- **Reports** — sales reports, top sellers, order/product/customer totals\n- **Media management** — list, delete, and cleanup orphaned media via WordPress REST API\n- **Token optimization** — all tools support a `fields` param to return only specific fields, reducing response size by 60-97%\n- **MCP resources** — schema references for products, orders, coupons, refunds, and payment gateways that agents can read for context\n- **Guided prompts** — multi-step workflows for variable product setup, order processing, and catalog overview\n- **Tool annotations** — `readOnlyHint`, `destructiveHint`, and `idempotentHint` on all 101 tools for safe agent behavior\n- **Actionable errors** — error responses include guidance on how to fix common issues\n\n## Safety\n\n> **This server connects to a LIVE WooCommerce store.** Every create, update, and delete operation affects real data. Use caution, especially on production stores.\n\n### Before You Start\n\n- **Back up your store** before using destructive tools. Use a WordPress backup plugin or your host's backup feature.\n- **Test on staging first.** Clone your production store to a staging environment and point this server at the staging URL.\n- **Use read-only mode** when exploring. Set `WOOCOMMERCE_MCP_READ_ONLY=true` to block all write operations — only list, get, and report tools will work.\n\n### Irreversible Operations\n\nMost delete operations move items to trash (recoverable). However, these are **permanent and cannot be undone**:\n\n| Tool | Why it's irreversible |\n| --- | --- |\n| `delete_media` | WordPress media deletions bypass trash entirely |\n| `delete_tax_rate` | Tax rates have no trash — deleted immediately |\n| `delete_tax_class` | Tax classes have no trash — rates become orphaned |\n| `delete_attribute` | Removes the attribute AND all its terms from every product |\n| `delete_refund` | Removes refund record (does not reverse payment) |\n| `cleanup_orphaned_media` | Permanently deletes all unattached media when `delete=true` |\n| `run_system_tool` | System maintenance actions (cache clears, DB updates) cannot be undone |\n\n### Cascading Effects\n\nSome operations affect more than the single item being changed:\n\n- **Deleting an attribute** removes it from all products — variable products may break\n- **Deleting an attribute term** removes that option from all products and variations\n- **Deleting a shipping zone** removes all methods and locations in that zone\n- **Batch operations** (`batch_update_attribute_terms`, `batch_update_variations`) can create, update, AND delete in a single call\n\n### API Key Permissions\n\nFor maximum safety, create WooCommerce API keys with only the permissions you need:\n- **Read-only exploration**: Create a key with **Read** permissions only\n- **Full management**: Use **Read/Write** permissions\n\n## Available Tools (101)\n\n| Domain | Tools |\n| --- | --- |\n| **Products** | list, get, create, update, delete |\n| **Categories** | list, get, create, update, delete |\n| **Tags** | list, get, create, update, delete |\n| **Brands** | list, get, create, update, delete |\n| **Attributes** | list, get, create, delete |\n| **Attribute Terms** | list, create, delete, batch update |\n| **Variations** | list, get, create, update, batch update |\n| **Orders** | list, get, create, update, delete |\n| **Order Refunds** | list, create, delete |\n| **Order Notes** | list, create, delete |\n| **Customers** | list, get, create, update |\n| **Coupons** | list, get, create, update, delete |\n| **Product Reviews** | list, get, update, delete |\n| **Shipping Zones** | list, get, create, update, delete |\n| **Shipping Zone Methods** | list, get, create, update, delete |\n| **Shipping Classes** | list, create |\n| **Tax Rates** | list, get, create, update, delete |\n| **Tax Classes** | list, create, delete |\n| **Webhooks** | list, get, create, update, delete |\n| **Payment Gateways** | list, get, update |\n| **Settings** | list groups, get, update |\n| **System Status** | get status, list tools, run tool |\n| **Data** | list countries, list currencies |\n| **Reports** | sales, top sellers, order/product/customer totals |\n| **Media** | list, delete, cleanup orphaned |\n\n## Resources\n\nThe server exposes 7 MCP resources that provide schema references and guides for AI agents:\n\n| URI | Description |\n| --- | --- |\n| `woo://schema/product` | Product fields, types, statuses, and key rules |\n| `woo://schema/order` | Order fields, status lifecycle, and payment info |\n| `woo://schema/coupon` | Coupon types, limits, restrictions, and rules |\n| `woo://schema/refund` | Refund fields, reasons, line items, and processing rules |\n| `woo://reference/product-types` | When to use simple, variable, grouped, or external products |\n| `woo://reference/order-statuses` | Order status transitions and lifecycle diagram |\n| `woo://reference/payment-gateways` | Available payment gateways and their configuration options |\n\nResources are read-only context that agents can fetch to understand WooCommerce data structures before making API calls.\n\n## Prompts\n\n5 guided workflow prompts that orchestrate multi-step operations:\n\n| Prompt | Args | What it does |\n| --- | --- | --- |\n| `setup_variable_product` | `product_name`, `attribute_name`, `variations` | Creates a variable product end-to-end: attribute → terms → product → variations → publish |\n| `process_order` | `order_id` | Reviews an order's details and recommends the appropriate status transition |\n| `catalog_overview` | _(none)_ | Runs 5 tools in parallel to produce a store dashboard (products, orders, customers, categories, top sellers) |\n| `handle_refund` | `order_id` | Guides through refund processing: review order, select items, create refund, verify |\n| `moderate_reviews` | _(none)_ | Reviews pending product reviews and recommends approve/update/delete actions |\n\n## Tool Annotations\n\nEvery tool is annotated with behavior hints so AI agents can make safe decisions:\n\n| Annotation | Meaning | Applied to |\n| --- | --- | --- |\n| `readOnlyHint` | No side effects, safe to call anytime | All `list_*`, `get_*`, and report tools (46) |\n| `destructiveHint` | Deletes or removes data | All `delete_*` tools + `cleanup_orphaned_media` + `run_system_tool` + `batch_update_*` (22) |\n| `idempotentHint` | Safe to retry, same result each time | All `update_*` tools (15) |\n\nAll tools also set `openWorldHint: false` — they only interact with WooCommerce, no external side effects.\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n| --- | --- | --- |\n| `WORDPRESS_SITE_URL` | Yes | WordPress store URL (e.g. `https://store.example.com`) |\n| `WOOCOMMERCE_CONSUMER_KEY` | Yes | WooCommerce REST API consumer key (`ck_...`) |\n| `WOOCOMMERCE_CONSUMER_SECRET` | Yes | WooCommerce REST API consumer secret (`cs_...`) |\n| `WORDPRESS_USERNAME` | No | WordPress admin username (for media tools) |\n| `WORDPRESS_APP_PASSWORD` | No | WordPress Application Password (for media tools) |\n| `MCP_TRANSPORT` | No | Set to `http` for remote HTTP access (default: `stdio`) |\n| `PORT` | No | Platform-provided port (Hostinger, Railway); overrides `MCP_PORT` |\n| `MCP_PORT` | No | HTTP server port (default: `3000`) |\n| `MCP_AUTH_TOKEN` | No* | Bearer token for HTTP auth (*required when `MCP_TRANSPORT=http`) |\n| `WOOCOMMERCE_MCP_READ_ONLY` | No | Set to `true` to block all write/delete operations (safe exploration mode) |\n\n### Using a `.env` file\n\nInstead of inlining credentials, point to a directory with a `.env` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"woocommerce\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@amitgurbani/mcp-server-woocommerce\"],\n      \"cwd\": \"/path/to/your/project\"\n    }\n  }\n}\n```\n\n### Multiple Stores\n\nUse different server names to manage multiple stores from one project:\n\n```json\n{\n  \"mcpServers\": {\n    \"store-a\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@amitgurbani/mcp-server-woocommerce\"],\n      \"env\": { \"WORDPRESS_SITE_URL\": \"https://store-a.com\", \"...\" }\n    },\n    \"store-b\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@amitgurbani/mcp-server-woocommerce\"],\n      \"env\": { \"WORDPRESS_SITE_URL\": \"https://store-b.com\", \"...\" }\n    }\n  }\n}\n```\n\n## Token Optimization\n\nAll tools support an optional `fields` param (comma-separated) to return only specific fields:\n\n```text\n# Browsing products — just names and prices\nfields: \"id,name,price\"\n\n# Stock check\nfields: \"id,name,stock_status,stock_quantity\"\n\n# Order overview\nfields: \"id,number,status,total\"\n```\n\nThis reduces response size by **60-97%**, keeping AI context windows focused and costs low.\n\n## Development\n\n```bash\ngit clone https://github.com/AmitGurbani/mcp-server-woocommerce.git\ncd mcp-server-woocommerce\npnpm install\n```\n\n```bash\npnpm dev               # Watch mode\npnpm build             # Build\npnpm start             # Run directly\npnpm test              # Run unit tests\npnpm test:integration  # Run integration tests (requires Docker)\npnpm test:watch        # Run unit tests in watch mode\npnpm inspector         # Debug with MCP Inspector\n```\n\n**Integration tests** run against a real WordPress 6.9.4 + WooCommerce 10.5.3 instance via [`@wordpress/env`](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-env/). Prerequisite: Docker. The test environment starts automatically when you run `pnpm test:integration`.\n\n### Docker\n\n```bash\ndocker build -t mcp-server-woocommerce .\ndocker run \\\n  -e WORDPRESS_SITE_URL=https://store.example.com \\\n  -e WOOCOMMERCE_CONSUMER_KEY=ck_your_key \\\n  -e WOOCOMMERCE_CONSUMER_SECRET=cs_your_secret \\\n  mcp-server-woocommerce\n```\n\n### Remote / Mobile Access (HTTP Transport)\n\nFor accessing your WooCommerce tools from Claude mobile, ChatGPT, or other remote clients, run the server in HTTP mode:\n\n```bash\nMCP_TRANSPORT=http MCP_AUTH_TOKEN=your-secret-token node build/index.js\n```\n\nOr with Docker:\n\n```bash\ndocker run -p 3000:3000 \\\n  -e MCP_TRANSPORT=http \\\n  -e MCP_AUTH_TOKEN=your-secret-token \\\n  -e WORDPRESS_SITE_URL=https://store.example.com \\\n  -e WOOCOMMERCE_CONSUMER_KEY=ck_your_key \\\n  -e WOOCOMMERCE_CONSUMER_SECRET=cs_your_secret \\\n  mcp-server-woocommerce\n```\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `MCP_TRANSPORT` | `stdio` | Set to `http` for remote access |\n| `PORT` | — | Platform-provided port (overrides `MCP_PORT`) |\n| `MCP_PORT` | `3000` | HTTP server port |\n| `MCP_AUTH_TOKEN` | — | Bearer token for authentication (Claude Desktop/Code) |\n| `AUTH0_DOMAIN` | — | Auth0 tenant URL for OAuth 2.1 (Claude.ai Connectors) |\n| `AUTH0_AUDIENCE` | — | Auth0 API identifier for OAuth 2.1 |\n| `MCP_SERVER_URL` | — | Public server URL for OAuth 2.1 discovery |\n\nEither `MCP_AUTH_TOKEN` or `AUTH0_DOMAIN` + `AUTH0_AUDIENCE` + `MCP_SERVER_URL` is required.\n\n**Deployment guide**: See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for step-by-step instructions for Railway (~$0/mo), Fly.io (~$0/mo with scale-to-zero), and Docker deployments.\n\n**Claude Desktop / Code**: Use bearer token auth — add the server URL and `Authorization: Bearer <token>` header to your config.\n\n**Claude.ai web / mobile**: Requires OAuth 2.1 via Auth0 (free tier). See the [deployment guide](docs/DEPLOYMENT.md#auth0-setup-for-claude-connectors) for setup instructions.\n\nDefault mode remains `stdio` — existing `npx` users are unaffected.\n\n## License\n\nMIT\n\n---\n\nWooCommerce is a registered trademark of Automattic Inc. This project is not affiliated with, endorsed by, or sponsored by Automattic Inc.\n",
  "bytes": 14668,
  "sha": "8f73c597dcf0ee190c365883e786b5ff1fa4f3ac4c2835ec7a2e29b89473ff83",
  "repo_slug": "amitgurbani/mcp-server-woocommerce",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_amitgurbani_mcp_server_woocomm_a5834d63/readme"
}