{"_id":"@arbazasif/woocommerce-mcp-server","name":"@arbazasif/woocommerce-mcp-server","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@arbazasif/woocommerce-mcp-server","version":"1.0.0","description":"Production-grade Model Context Protocol (MCP) server for WooCommerce — manage orders, products, customers, inventory and analytics with Claude AI or any MCP client","main":"build/index.js","type":"module","bin":{"woocommerce-mcp-server":"build/index.js"},"scripts":{"build":"tsc","dev":"tsc --watch","start":"node build/index.js","inspect":"npx @modelcontextprotocol/inspector build/index.js","prepare":"npm run build"},"keywords":["mcp","model-context-protocol","woocommerce","wordpress","woocommerce-ai","woocommerce-agent","claude","claude-mcp","ai-agent","ecommerce-ai","woocommerce-automation","woocommerce-claude","shop-management","order-management","inventory-management","anthropic","llm-tools"],"author":{"name":"arbazasif"},"license":"MIT","homepage":"https://github.com/arbazex/woocommerce-mcp-server","repository":{"type":"git","url":"git+https://github.com/arbazex/woocommerce-mcp-server.git"},"bugs":{"url":"https://github.com/arbazex/woocommerce-mcp-server/issues"},"engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^1.10.2","axios":"^1.9.0","axios-retry":"^4.5.0","zod":"^3.25.20"},"devDependencies":{"@types/node":"^22.19.17","typescript":"^5.8.3"},"_id":"@arbazasif/woocommerce-mcp-server@1.0.0","gitHead":"1ea3130290002cfe3dc2ed7d09538c0b879b8b42","types":"./build/index.d.ts","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-ymeOpqjJPOtWDfifC28h13qolFgYEC9/S7uGoLgIvZed2JRiUzJ3F6zaulJTaoRcqEn6kYpbBV90hwNlKUXfSA==","shasum":"afcf38b4dfb5a4c360c5e49e774380e635657c38","tarball":"https://registry.npmjs.org/@arbazasif/woocommerce-mcp-server/-/woocommerce-mcp-server-1.0.0.tgz","fileCount":35,"unpackedSize":129647,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDYhL6XablyabZxJ07K5I2KTcSYmUh3Kfw8SuZgW9Y8iwIhAMAeVcR7b1eBk5ePvNUPnO9Fj66ZqpbnmZuwcfKCcxAa"}]},"_npmUser":{"name":"arbazasif","email":"muhammadarbazasif@gmail.com"},"directories":{},"maintainers":[{"name":"arbazasif","email":"muhammadarbazasif@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/woocommerce-mcp-server_1.0.0_1777202390216_0.11113732300739065"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-26T11:19:50.099Z","1.0.0":"2026-04-26T11:19:50.375Z","modified":"2026-04-26T11:19:50.733Z"},"maintainers":[{"name":"arbazasif","email":"muhammadarbazasif@gmail.com"}],"description":"Production-grade Model Context Protocol (MCP) server for WooCommerce — manage orders, products, customers, inventory and analytics with Claude AI or any MCP client","homepage":"https://github.com/arbazex/woocommerce-mcp-server","keywords":["mcp","model-context-protocol","woocommerce","wordpress","woocommerce-ai","woocommerce-agent","claude","claude-mcp","ai-agent","ecommerce-ai","woocommerce-automation","woocommerce-claude","shop-management","order-management","inventory-management","anthropic","llm-tools"],"repository":{"type":"git","url":"git+https://github.com/arbazex/woocommerce-mcp-server.git"},"author":{"name":"arbazasif"},"bugs":{"url":"https://github.com/arbazex/woocommerce-mcp-server/issues"},"license":"MIT","readme":"# woocommerce-mcp-server\r\n\r\n> **Production-grade Model Context Protocol (MCP) server for WooCommerce** — manage orders, products, customers, inventory, and analytics using Claude AI or any MCP-compatible client.\r\n\r\n[![npm version](https://img.shields.io/npm/v/woocommerce-mcp-server)](https://www.npmjs.com/package/woocommerce-mcp-server)\r\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\r\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)\r\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue)](https://www.typescriptlang.org)\r\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org)\r\n\r\n---\r\n\r\n## 🎥 What You Can Do\r\n\r\nOnce connected, just talk to Claude naturally:\r\n\r\n> *\"Show me all processing orders from this week\"*\r\n> *\"Which products are running low on stock?\"*\r\n> *\"Find the product with SKU WOO-1234\"*\r\n> *\"What's my revenue this month?\"*\r\n> *\"Who are my newest customers?\"*\r\n> *\"Mark order #501 as completed\"*\r\n\r\nNo more clicking through WooCommerce dashboards. Your AI handles it.\r\n\r\n---\r\n\r\n## ✨ Features\r\n\r\n- ✅ **20 production-ready tools** across Orders, Products, Customers, and Analytics\r\n- ✅ **TypeScript** — fully typed, no runtime surprises\r\n- ✅ **Retry logic** — automatic retries on network errors and rate limits\r\n- ✅ **Meaningful error messages** — no raw API errors thrown at users\r\n- ✅ **Input validation** via Zod — bad inputs rejected before they hit the API\r\n- ✅ **Works with Claude Desktop**, MCP Inspector, and any MCP-compatible client\r\n- ✅ **npm installable** — no cloning required\r\n\r\n---\r\n\r\n## 🛠️ Tools Reference\r\n\r\n### 📦 Orders (5 tools)\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `list_orders` | List orders with filters (status, date, customer) |\r\n| `get_order` | Full details for a single order |\r\n| `update_order_status` | Change order status + optional note |\r\n| `get_order_notes` | All notes on an order |\r\n| `add_order_note` | Add internal or customer-visible note |\r\n\r\n### 🏷️ Products (7 tools)\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `list_products` | Browse catalog with filters |\r\n| `get_product` | Full details for a single product |\r\n| `update_product` | Update price, stock, status, description |\r\n| `get_low_stock_products` | Products at or below stock threshold |\r\n| `get_out_of_stock_products` | All out-of-stock products |\r\n| `search_products_by_sku` | Find product by exact SKU |\r\n| `list_product_categories` | All categories with counts |\r\n\r\n### 👥 Customers (4 tools)\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `list_customers` | Browse customers with search |\r\n| `get_customer` | Full customer profile |\r\n| `get_customer_orders` | All orders for a customer |\r\n| `get_recent_customers` | New customers in last N days |\r\n\r\n### 📊 Analytics (4 tools)\r\n\r\n| Tool | Description |\r\n|------|-------------|\r\n| `get_revenue_summary` | Sales, orders, avg order value by period |\r\n| `get_sales_report` | Detailed report with tax, shipping, refunds |\r\n| `get_top_selling_products` | Best sellers by quantity |\r\n| `get_order_status_counts` | Order count breakdown by status |\r\n\r\n---\r\n\r\n## 🚀 Quick Setup\r\n\r\n### Prerequisites\r\n\r\n- Node.js 18+\r\n- A WooCommerce store with REST API access\r\n- Claude Desktop (for AI integration)\r\n\r\n### Step 1 — Generate WooCommerce API Keys\r\n\r\n1. Go to your WordPress dashboard\r\n2. Navigate to **WooCommerce → Settings → Advanced → REST API**\r\n3. Click **Add Key**\r\n4. Set Description: `MCP Server`\r\n5. Set Permissions: **Read/Write**\r\n6. Click **Generate API Key**\r\n7. Copy your **Consumer Key** and **Consumer Secret**\r\n\r\n### Step 2 — Install via npx (Recommended)\r\n\r\nNo installation needed. Configure Claude Desktop directly:\r\n\r\nOpen your Claude Desktop config file:\r\n\r\n- **Windows:** `C:\\Users\\<YourName>\\AppData\\Roaming\\Claude\\claude_desktop_config.json`\r\n- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\r\n\r\nAdd this configuration:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"woocommerce\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"woocommerce-mcp-server\"],\r\n      \"env\": {\r\n        \"WOOCOMMERCE_URL\": \"https://yourstore.com\",\r\n        \"WOOCOMMERCE_CONSUMER_KEY\": \"ck_your_consumer_key_here\",\r\n        \"WOOCOMMERCE_CONSUMER_SECRET\": \"cs_your_consumer_secret_here\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\nRestart Claude Desktop. You should see a 🔌 plug icon — your WooCommerce store is now connected.\r\n\r\n---\r\n\r\n### Alternative — Clone and Run Locally\r\n\r\n```bash\r\ngit clone https://github.com/arbazex/woocommerce-mcp-server.git\r\ncd woocommerce-mcp-server\r\nnpm install\r\n```\r\n\r\nCreate a `.env` file:\r\n\r\n```env\r\nWOOCOMMERCE_URL=https://yourstore.com\r\nWOOCOMMERCE_CONSUMER_KEY=ck_your_key_here\r\nWOOCOMMERCE_CONSUMER_SECRET=cs_your_secret_here\r\n```\r\n\r\nBuild and run:\r\n\r\n```bash\r\nnpm run build\r\nnode build/index.js\r\n```\r\n\r\nThen update your Claude Desktop config to point to your local build:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"woocommerce\": {\r\n      \"command\": \"node\",\r\n      \"args\": [\"C:\\\\path\\\\to\\\\woocommerce-mcp-server\\\\build\\\\index.js\"],\r\n      \"env\": {\r\n        \"WOOCOMMERCE_URL\": \"https://yourstore.com\",\r\n        \"WOOCOMMERCE_CONSUMER_KEY\": \"ck_your_key_here\",\r\n        \"WOOCOMMERCE_CONSUMER_SECRET\": \"cs_your_secret_here\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n---\r\n\r\n## 🧪 Testing with MCP Inspector\r\n\r\nTest your tools in the browser without Claude Desktop:\r\n\r\n```bash\r\nnpx @modelcontextprotocol/inspector build/index.js\r\n```\r\n\r\nSet environment variables first:\r\n\r\n```powershell\r\n# Windows PowerShell\r\n$env:WOOCOMMERCE_URL=\"https://yourstore.com\"\r\n$env:WOOCOMMERCE_CONSUMER_KEY=\"ck_your_key\"\r\n$env:WOOCOMMERCE_CONSUMER_SECRET=\"cs_your_secret\"\r\n```\r\n\r\n```bash\r\n# macOS/Linux\r\nexport WOOCOMMERCE_URL=\"https://yourstore.com\"\r\nexport WOOCOMMERCE_CONSUMER_KEY=\"ck_your_key\"\r\nexport WOOCOMMERCE_CONSUMER_SECRET=\"cs_your_secret\"\r\n```\r\n\r\n---\r\n\r\n## 🔑 API Key Permissions\r\n\r\n| Feature | Required Permission |\r\n|---------|-------------------|\r\n| Read orders, products, customers, analytics | **Read** |\r\n| Update order status, add notes, update products | **Read/Write** |\r\n\r\n> ⚠️ Without Write permissions, update tools will return an authentication error. Generate a Read/Write key for full functionality.\r\n\r\n---\r\n\r\n## 📁 Project Structure\r\n\r\n```\r\nwoocommerce-mcp-server/\r\n├── src/\r\n│   ├── index.ts          # Entry point (stdio transport)\r\n│   ├── server.ts         # MCP server setup\r\n│   ├── woo-client.ts     # WooCommerce API client (retry + error handling)\r\n│   ├── types/\r\n│   │   └── woo-types.ts  # Full TypeScript type definitions\r\n│   └── tools/\r\n│       ├── orders.ts     # Order management tools\r\n│       ├── products.ts   # Product management tools\r\n│       ├── customers.ts  # Customer management tools\r\n│       └── analytics.ts  # Reporting and analytics tools\r\n├── build/                # Compiled output (generated)\r\n├── package.json\r\n├── tsconfig.json\r\n└── .env.example\r\n```\r\n\r\n---\r\n\r\n## 🔒 Security\r\n\r\n- API credentials are passed via **environment variables** — never hardcoded\r\n- All inputs are **validated with Zod** before hitting the API\r\n- Rate limit errors are handled gracefully with **automatic retry + backoff**\r\n- No credentials are logged to stdout (only stderr for debug messages)\r\n\r\n---\r\n\r\n## 🛠️ Development\r\n\r\n```bash\r\n# Install dependencies\r\nnpm install\r\n\r\n# Watch mode (auto-rebuild on save)\r\nnpm run dev\r\n\r\n# Build once\r\nnpm run build\r\n\r\n# Open MCP Inspector\r\nnpm run inspect\r\n```\r\n\r\n---\r\n\r\n## 🤝 Contributing\r\n\r\nContributions are welcome! If you have ideas for new tools or find a bug:\r\n\r\n1. Fork the repo\r\n2. Create a branch: `git checkout -b feature/your-tool-name`\r\n3. Make your changes\r\n4. Open a Pull Request\r\n\r\n---\r\n\r\n## 📋 Roadmap\r\n\r\n- [ ] Create order tool\r\n- [ ] Coupon management tools\r\n- [ ] Webhook management\r\n- [ ] Product variation support\r\n- [ ] Remote HTTP (Streamable HTTP) transport for hosted deployment\r\n- [ ] Batch operations support\r\n\r\n---\r\n\r\n## 📄 License\r\n\r\nMIT © [Arbaz](https://github.com/arbazex)\r\n\r\n---\r\n\r\n*Built with ❤️ by Arbaz*","readmeFilename":"README.md","_rev":"1-21b805c4c30d6dbd2118f7ee5cf2e456"}