MCP Woocommerce Integration

MCP Integration for WooCommerce

🚀 Description

WordPress/WooCommerce plugin that implements the Model Context Protocol (MCP) to allow full control of the store by AI agents.

📍 Repository

📦 Installation

⚠️ IMPORTANT: How to Install Correctly

GitHub adds branch name to ZIP (-main), then you need to rename the folder:

Method 1: Rename and Repack (Recommended)

1. Clique em Code → Download ZIP no GitHub
2. Extract the file mcp-woocommerce-integration-main.zip
3. Renomeie the folder extracted from mcp-woocommerce-integration-main para mcp-woocommerce
4. Compact the folder again mcp-woocommerce (right click → Send to → Compacted folder)
5. No WordPress: Plugins → Add New → Submit Plugin
6. Upload the new ZIP file and click Install Now
7. Ative o plugin

Method 2: Via FTP (Faster)

1. Download and extract the GitHub ZIP
2. Rename the folder to mcp-woocommerce
3. Send via FTP to /wp-content/plugins/mcp-woocommerce/
4. Active in the WordPress dashboard

Method 3: Clone via Git (Advanced)

cd /caminho/para/wp-content/plugins/
git clone https://github.com/marcelosolelua-ux/mcp-woocommerce-integration.git mcp-woocommerce

Expected Structure After Installation

/wp-content/plugins/mcp-woocommerce/
├── mcp-woocommerce.php          (arquivo principal)
├── README.md
├── inc/
│   ├── rest.php
│   ├── utils.php
│   ├── executor.php
│   ├── class-admin.php
│   └── methods/
│       ├── class-product.php
│       ├── class-order.php
│       ├── class-customer.php
│       └── class-store.php
└── logs/

Requirements

• WordPress 5.0+
• WooCommerce 5.0+
• PHP 7.4+

🛠️ Configuration

1. After activating, go to MCP WooCommerce no menu lateral
2. Clique em Generate New Token
3. Give a name and select the permissions (Read/Write/Admin)
4. Copy the generated token
5. Use o endpoint: https://seusite.com/wp-json/mcp/v1/execute

Quick setup in GPTMaker (MCP Terminal)

• MCP server URL: https://seusite.com/wp-json/mcp/v1/execute
• Authentication: send the token to the header X-MCP-Key: ou Authorization: Bearer (GPTMaker usually uses the Bearer standard).
• Automatic Capabilities: https://seusite.com/wp-json/mcp/v1/capabilities returns the JSON manifest ready to be imported into the GPTMaker panel (includes support for Authorization: Bearer).
• Formato: JSON-RPC 2.0 (campos jsonrpc, id, method, params).

🔐 Authentication

All requests must include the header:

X-MCP-Key: seu_token_de_64_caracteres

📡 Endpoint

POST /wp-json/mcp/v1/execute
Content-Type: application/json

📝 Example of Request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "wc.list_products",
  "params": {
    "page": 1,
    "per_page": 10
  }
}

Exemplo com cURL

curl -X POST https://seusite.com/wp-json/mcp/v1/execute \
  -H "Content-Type: application/json" \
  -H "X-MCP-Key: seu_token_aqui" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "wc.get_product",
    "params": {"id": 123}
  }'

📚 Available Methods

Products

• wc.get_product - Get product by ID
• wc.search_products - Search products by name/SKU
• wc.list_products - List products with pagination
• wc.update_stock - Update stock
• wc.update_price - Update price
• wc.create_product - Create a new product

Orders

• wc.get_order - Order by ID
• wc.list_orders - List orders
• wc.create_order - Create new order
• wc.update_order_status - Update order status

Clients

• wc.get_customer - Get customer by ID or email
• wc.list_customers - List customers
• wc.create_customer - Create new customer

Shop

• wc.get_store_info - General store information
• wc.get_categories - List product categories
• wc.get_coupons - List active coupons

🛡️ Security

• ✅ Rate limiting: 60 requests/minute per token
• ✅ Automatic locking after 5 consecutive errors
• ✅ Detailed logs of all operations
• ✅ Complete sanitation of inputs
• ✅ Granular permission system (read/write/admin)
• ✅ 64-character tokens generated with random_bytes()

📄 Capabilities JSON

The plugin generates the automatic manifest for AI agents:

• Endpoint REST: https://seusite.com/wp-json/mcp/v1/capabilities
• Local file (optional): https://seusite.com/wp-content/plugins/mcp-woocommerce/capabilities.json

🐛 Problem Solving

Plugin not listed

• Check if the folder is named as mcp-woocommerce (sem -main)
• Confirm that the file mcp-woocommerce.php is at the root of the plugin folder
• Check if WooCommerce is active

Error Activating

• Make sure WooCommerce is installed
• Check PHP version (minimum 7.4)
• Check logs in /wp-content/plugins/mcp-woocommerce/logs/

Token does not work

• Check if the header is X-MCP-Key (with name)
• Confirm that the token is active in the admin panel
• See the logs for details of the error

📝 Logs

All logs are saved to:

/wp-content/plugins/mcp-woocommerce/logs/mcp-logs.log

You can also view them in the panel MCP WooCommerce → Recent Logs

✅ Local rapid tests

To validate PHP syntax before installing on WordPress, run at the root of the repository:

for f in mcp-woocommerce.php $(find inc -name '*.php'); do php -l "$f"; done

The command should return "No syntax errors detected" for all files.

The file capabilities.json is automatically regenerated on each plugin load if the version or protocol changes, ensuring that the manifest used by GPTMaker is always synchronized.

📄 License

MIT License

👨‍💻 Author

Developed by ChatGPT according to RPD v1.0 specifications

🔗 Links Úteis

• WooCommerce REST API documentation
• JSON-RPC 2.0 Specification
• Model Context Protocol