{"_id":"@amitgurbani/mcp-server-woocommerce","_rev":"4-0eaeefec099e4f65496b3ce1f917a0e9","name":"@amitgurbani/mcp-server-woocommerce","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"@amitgurbani/mcp-server-woocommerce","version":"1.0.0","keywords":["mcp","mcp-server","woocommerce","model-context-protocol","claude","ai","wordpress","ecommerce","store-management","automation","integration","api"],"author":{"name":"Amit Gurbani"},"license":"MIT","_id":"@amitgurbani/mcp-server-woocommerce@1.0.0","maintainers":[{"name":"amitgurbani","email":"amit1994.gurbani@gmail.com"}],"homepage":"https://github.com/AmitGurbani/mcp-server-woocommerce","bugs":{"url":"https://github.com/AmitGurbani/mcp-server-woocommerce/issues"},"bin":{"mcp-server-woocommerce":"build/index.js"},"dist":{"shasum":"33c7449a4e926e88db2bd4e7c7955bbbd76441e0","tarball":"https://registry.npmjs.org/@amitgurbani/mcp-server-woocommerce/-/mcp-server-woocommerce-1.0.0.tgz","fileCount":91,"integrity":"sha512-x05rw7IwTkRCrZt1S/hypGSczHAT/vfjwt8McbGD2U4RlV0oYKlpzCBKIiJPNVklxMjaNZJXQgGWBf13XWP1hg==","signatures":[{"sig":"MEUCIDrWVymdzr8w2od//+vlYCBf9+6P0/1LylFqjwNVbyvHAiEA8dQgAQug57zFjM9i4vhcrVC3uQaPi+n/Wg1FM7m7lYs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@amitgurbani%2fmcp-server-woocommerce@1.0.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":236902},"type":"module","_from":"file:amitgurbani-mcp-server-woocommerce-1.0.0.tgz","engines":{"node":">=18"},"scripts":{"dev":"tsc --watch","lint":"eslint src/","test":"vitest run","build":"pnpm run clean && tsc","clean":"rm -rf build","start":"node build/index.js","format":"prettier --write src/","lint:fix":"eslint src/ --fix","inspector":"npx @modelcontextprotocol/inspector node build/index.js","test:watch":"vitest","format:check":"prettier --check src/"},"_npmUser":{"name":"amitgurbani","email":"amit1994.gurbani@gmail.com"},"_resolved":"/tmp/b5be064138b6650c8fd6600f33d5f780/amitgurbani-mcp-server-woocommerce-1.0.0.tgz","_integrity":"sha512-x05rw7IwTkRCrZt1S/hypGSczHAT/vfjwt8McbGD2U4RlV0oYKlpzCBKIiJPNVklxMjaNZJXQgGWBf13XWP1hg==","repository":{"url":"git+https://github.com/AmitGurbani/mcp-server-woocommerce.git","type":"git"},"_npmVersion":"10.9.4","description":"MCP server for managing WooCommerce stores through AI assistants","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^4.3.6","dotenv":"^17.3.1","@modelcontextprotocol/sdk":"^1.27.1","@woocommerce/woocommerce-rest-api":"^1.0.2"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.0.3","vitest":"^4.0.18","prettier":"^3.8.1","typescript":"^5.9.3","@types/node":"^25.4.0","typescript-eslint":"^8.57.0","eslint-config-prettier":"^10.1.8","@typescript-eslint/parser":"^8.57.0","@typescript-eslint/eslint-plugin":"^8.57.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-woocommerce_1.0.0_1773142961765_0.8589546955157632","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@amitgurbani/mcp-server-woocommerce","version":"1.0.1","keywords":["mcp","mcp-server","woocommerce","model-context-protocol","claude","ai","wordpress","ecommerce","store-management","automation","integration","api"],"author":{"name":"Amit Gurbani"},"license":"MIT","_id":"@amitgurbani/mcp-server-woocommerce@1.0.1","maintainers":[{"name":"amitgurbani","email":"amit1994.gurbani@gmail.com"}],"homepage":"https://github.com/AmitGurbani/mcp-server-woocommerce","bugs":{"url":"https://github.com/AmitGurbani/mcp-server-woocommerce/issues"},"bin":{"mcp-server-woocommerce":"build/index.js"},"dist":{"shasum":"b7de220443d92afde938d3d905011f0657f52183","tarball":"https://registry.npmjs.org/@amitgurbani/mcp-server-woocommerce/-/mcp-server-woocommerce-1.0.1.tgz","fileCount":91,"integrity":"sha512-bAVj77te3HkQUht2Qld7HVJKvLrl8k3GM8CQE8aQ5zQqWrtfFPUTPT5AVGmK0k7VA9488yFRiTW75FWevRTVhQ==","signatures":[{"sig":"MEYCIQClI07Qqyv3538W07J3ZVy9C57xJPE4T1j+jtpVC3Q0aAIhAPRq9pqEQCsUhG2yR/xvXA49vn3taPlZLFHalsmT8E5l","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@amitgurbani%2fmcp-server-woocommerce@1.0.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":236963},"type":"module","_from":"file:amitgurbani-mcp-server-woocommerce-1.0.1.tgz","engines":{"node":">=18"},"mcpName":"io.github.AmitGurbani/mcp-server-woocommerce","scripts":{"dev":"tsc --watch","lint":"eslint src/","test":"vitest run","build":"pnpm run clean && tsc","clean":"rm -rf build","start":"node build/index.js","format":"prettier --write src/","lint:fix":"eslint src/ --fix","inspector":"npx @modelcontextprotocol/inspector node build/index.js","test:watch":"vitest","format:check":"prettier --check src/"},"_npmUser":{"name":"amitgurbani","email":"amit1994.gurbani@gmail.com"},"_resolved":"/tmp/ad35f6289528b72412026d4db9c98804/amitgurbani-mcp-server-woocommerce-1.0.1.tgz","_integrity":"sha512-bAVj77te3HkQUht2Qld7HVJKvLrl8k3GM8CQE8aQ5zQqWrtfFPUTPT5AVGmK0k7VA9488yFRiTW75FWevRTVhQ==","repository":{"url":"git+https://github.com/AmitGurbani/mcp-server-woocommerce.git","type":"git"},"_npmVersion":"10.9.4","description":"MCP server for managing WooCommerce stores through AI assistants","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^4.3.6","dotenv":"^17.3.1","@modelcontextprotocol/sdk":"^1.27.1","@woocommerce/woocommerce-rest-api":"^1.0.2"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.0.3","vitest":"^4.0.18","prettier":"^3.8.1","typescript":"^5.9.3","@types/node":"^25.4.0","typescript-eslint":"^8.57.0","eslint-config-prettier":"^10.1.8","@typescript-eslint/parser":"^8.57.0","@typescript-eslint/eslint-plugin":"^8.57.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-woocommerce_1.0.1_1773144110414_0.3786767470532586","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@amitgurbani/mcp-server-woocommerce","version":"1.1.0","keywords":["mcp","mcp-server","woocommerce","model-context-protocol","claude","ai","wordpress","ecommerce","store-management","automation","integration","api"],"author":{"name":"Amit Gurbani"},"license":"MIT","_id":"@amitgurbani/mcp-server-woocommerce@1.1.0","maintainers":[{"name":"amitgurbani","email":"amit1994.gurbani@gmail.com"}],"homepage":"https://github.com/AmitGurbani/mcp-server-woocommerce","bugs":{"url":"https://github.com/AmitGurbani/mcp-server-woocommerce/issues"},"bin":{"mcp-server-woocommerce":"build/index.js"},"dist":{"shasum":"620e418e3ddd7e195d101b3a3f496ef48c68c9b6","tarball":"https://registry.npmjs.org/@amitgurbani/mcp-server-woocommerce/-/mcp-server-woocommerce-1.1.0.tgz","fileCount":115,"integrity":"sha512-aqTBZCoO4SnvJCMvE0i+Q1fH48u0DDOs3akxXbGeqxg5O4iDutfFAq5v0eXdSBkAcHUBTwSKv98BE0tL7Vw2vg==","signatures":[{"sig":"MEQCIFttv6y1VdBaMh+WyIFUPRrPuCiiZae+NCqm50fs25YjAiB6gXk/QOlqoAhjH0sSzEbqw5+ZBmdRmmLGheB4qHEvXA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@amitgurbani%2fmcp-server-woocommerce@1.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":281668},"type":"module","_from":"file:amitgurbani-mcp-server-woocommerce-1.1.0.tgz","engines":{"node":">=18"},"mcpName":"io.github.AmitGurbani/mcp-server-woocommerce","scripts":{"dev":"tsc --watch","lint":"eslint src/","test":"vitest run","build":"pnpm run clean && tsc","clean":"rm -rf build","start":"node build/index.js","format":"prettier --write src/","lint:fix":"eslint src/ --fix","inspector":"npx @modelcontextprotocol/inspector node build/index.js","test:watch":"vitest","format:check":"prettier --check src/"},"_npmUser":{"name":"amitgurbani","email":"amit1994.gurbani@gmail.com"},"_resolved":"/tmp/3761bbeb20cc52dfacc65a6308d907f4/amitgurbani-mcp-server-woocommerce-1.1.0.tgz","_integrity":"sha512-aqTBZCoO4SnvJCMvE0i+Q1fH48u0DDOs3akxXbGeqxg5O4iDutfFAq5v0eXdSBkAcHUBTwSKv98BE0tL7Vw2vg==","repository":{"url":"git+https://github.com/AmitGurbani/mcp-server-woocommerce.git","type":"git"},"_npmVersion":"10.9.4","description":"MCP server for managing WooCommerce stores through AI assistants","directories":{},"_nodeVersion":"22.22.0","dependencies":{"zod":"^4.3.6","dotenv":"^17.3.1","@modelcontextprotocol/sdk":"^1.27.1","@woocommerce/woocommerce-rest-api":"^1.0.2"},"_hasShrinkwrap":false,"devDependencies":{"eslint":"^10.0.3","vitest":"^4.0.18","prettier":"^3.8.1","typescript":"^5.9.3","@types/node":"^25.4.0","typescript-eslint":"^8.57.0","eslint-config-prettier":"^10.1.8","@typescript-eslint/parser":"^8.57.0","@typescript-eslint/eslint-plugin":"^8.57.0"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server-woocommerce_1.1.0_1773230100331_0.5295836286412394","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@amitgurbani/mcp-server-woocommerce","mcpName":"io.github.AmitGurbani/mcp-server-woocommerce","version":"1.2.0","description":"MCP server for managing WooCommerce stores through AI assistants","type":"module","author":{"name":"Amit Gurbani"},"license":"MIT","homepage":"https://github.com/AmitGurbani/mcp-server-woocommerce","bugs":{"url":"https://github.com/AmitGurbani/mcp-server-woocommerce/issues"},"repository":{"type":"git","url":"git+https://github.com/AmitGurbani/mcp-server-woocommerce.git"},"keywords":["mcp","mcp-server","woocommerce","model-context-protocol","claude","ai","wordpress","ecommerce","store-management","automation","integration","api"],"engines":{"node":">=18"},"bin":{"mcp-server-woocommerce":"build/index.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.27.1","@woocommerce/woocommerce-rest-api":"^1.0.2","dotenv":"^17.3.1","zod":"^4.3.6"},"devDependencies":{"@types/node":"^25.4.0","@typescript-eslint/eslint-plugin":"^8.57.0","@typescript-eslint/parser":"^8.57.0","@wordpress/env":"^11.1.0","eslint":"^10.0.3","eslint-config-prettier":"^10.1.8","prettier":"^3.8.1","typescript":"^5.9.3","typescript-eslint":"^8.57.0","vitest":"^4.0.18"},"scripts":{"clean":"rm -rf build","build":"pnpm run clean && tsc","dev":"tsc --watch","start":"node build/index.js","inspector":"npx @modelcontextprotocol/inspector node build/index.js","test":"vitest run","test:integration":"vitest run --config vitest.config.integration.ts","test:watch":"vitest","wp-env":"wp-env","lint":"eslint src/","lint:fix":"eslint src/ --fix","format":"prettier --write src/","format:check":"prettier --check src/"},"_id":"@amitgurbani/mcp-server-woocommerce@1.2.0","_integrity":"sha512-WWxzwwoyQxu37ipzwQ3azZgmd2/+wanGZbaWtbuStN6ET/O+a+XuZHF4pInWMkjY7GS0sGPjNwUIMd9IrvnUBg==","_resolved":"/tmp/b620646617ab2af7420025d2fa7473be/amitgurbani-mcp-server-woocommerce-1.2.0.tgz","_from":"file:amitgurbani-mcp-server-woocommerce-1.2.0.tgz","_nodeVersion":"22.22.0","_npmVersion":"10.9.4","dist":{"integrity":"sha512-WWxzwwoyQxu37ipzwQ3azZgmd2/+wanGZbaWtbuStN6ET/O+a+XuZHF4pInWMkjY7GS0sGPjNwUIMd9IrvnUBg==","shasum":"1dd3d66169a5cf84be63514d401deb2b87609997","tarball":"https://registry.npmjs.org/@amitgurbani/mcp-server-woocommerce/-/mcp-server-woocommerce-1.2.0.tgz","fileCount":119,"unpackedSize":296241,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@amitgurbani%2fmcp-server-woocommerce@1.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDj6EVvIzg5MQgr8rm3lbgRzPq7CrbQ4nsnySJn2n6ZiwIhAM0s8oaYxPhmRxq3OhzFG2zMaPFsQtirgJYLyFjKCvZz"}]},"_npmUser":{"name":"amitgurbani","email":"amit1994.gurbani@gmail.com"},"directories":{},"maintainers":[{"name":"amitgurbani","email":"amit1994.gurbani@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server-woocommerce_1.2.0_1773334029739_0.006656368681389857"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-10T11:42:41.669Z","modified":"2026-03-12T16:47:10.185Z","1.0.0":"2026-03-10T11:42:41.906Z","1.0.1":"2026-03-10T12:01:50.602Z","1.1.0":"2026-03-11T11:55:00.467Z","1.2.0":"2026-03-12T16:47:09.881Z"},"bugs":{"url":"https://github.com/AmitGurbani/mcp-server-woocommerce/issues"},"author":{"name":"Amit Gurbani"},"license":"MIT","homepage":"https://github.com/AmitGurbani/mcp-server-woocommerce","keywords":["mcp","mcp-server","woocommerce","model-context-protocol","claude","ai","wordpress","ecommerce","store-management","automation","integration","api"],"repository":{"type":"git","url":"git+https://github.com/AmitGurbani/mcp-server-woocommerce.git"},"description":"MCP server for managing WooCommerce stores through AI assistants","maintainers":[{"name":"amitgurbani","email":"amit1994.gurbani@gmail.com"}],"readme":"# 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| `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| `MCP_PORT` | `3000` | HTTP server port |\n| `MCP_AUTH_TOKEN` | _(required)_ | Bearer token for authentication |\n\n**Deployment**: Deploy to **Railway**, **Fly.io**, or any container host that supports Docker or Node.js. Set the three WooCommerce env vars plus `MCP_TRANSPORT=http` and `MCP_AUTH_TOKEN`.\n\n**Claude mobile / web**: Once deployed, go to [Claude.ai](https://claude.ai) → **Settings** → **Connectors** → **Add Custom Connector**. Enter your server's public URL (e.g. `https://your-app.railway.app/mcp`) and the bearer token you set as `MCP_AUTH_TOKEN`. Your WooCommerce tools will then be available in Claude conversations on mobile and web.\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","readmeFilename":"README.md"}