@wppoland/woocommerce-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WPPoland (wppoland.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,97 @@
+# woocommerce-mcp
+
+A small, read-only [Model Context Protocol](https://modelcontextprotocol.io) server for **WordPress + WooCommerce**. It lets Claude (or any MCP client) answer questions about a live store — products, orders, sales, and blog posts — over the official REST APIs. No writes, no plugins to install on the store: it talks to the existing WordPress/WooCommerce REST endpoints.
+
+Built and maintained by [WPPoland](https://wppoland.com/en/) — senior WordPress & WooCommerce engineering. If you need this wired into a real store stack, we build [WooCommerce ERP and API integrations](https://wppoland.com/en/woocommerce-erp-integration/) and [enterprise e-commerce architecture](https://wppoland.com/en/enterprise-solutions/) (headless, integrations, AI-ready data).
+
+## Tools
+
+| Tool | What it does | Needs WooCommerce keys |
+|------|--------------|:---:|
+| `list_products` | List / search products (name, sku, price, stock, permalink) | yes |
+| `get_product` | Full details for one product by id | yes |
+| `list_orders` | Recent orders, newest first, optional status filter | yes |
+| `sales_report` | Sales totals for a period (week / month / last_month / year) | yes |
+| `search_posts` | Search published blog posts (public WP REST API) | no |
+
+Everything is **read-only**. The server never creates, edits, or deletes anything in the store.
+
+## Install & build
+
+From npm (package name is scoped - the unscoped `woocommerce-mcp` name is locked on the registry):
+
+```bash
+npm install -g @wppoland/woocommerce-mcp
+# or: npx @wppoland/woocommerce-mcp
+```
+
+From source:
+
+```bash
+git clone https://github.com/wppoland/woocommerce-mcp.git
+cd woocommerce-mcp
+npm install
+npm run build
+```
+
+## Configure
+
+Set three environment variables:
+
+| Var | Required | Example |
+|-----|:---:|---------|
+| `WP_URL` | yes | `https://shop.example.com` |
+| `WC_CONSUMER_KEY` | for `wc_*` tools | `ck_xxx` |
+| `WC_CONSUMER_SECRET` | for `wc_*` tools | `cs_xxx` |
+
+Create the WooCommerce keys in **WooCommerce → Settings → Advanced → REST API → Add key** with **Read** permission. `search_posts` works without keys against any public WordPress site.
+
+> The keys are sent to your own store over HTTPS as REST query auth. Use HTTPS, and give the key **Read** access only.
+
+## Use with Claude Desktop / Claude Code
+
+Add to your MCP client config (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "woocommerce": {
+      "command": "node",
+      "args": ["/absolute/path/to/woocommerce-mcp/dist/index.js"],
+      "env": {
+        "WP_URL": "https://shop.example.com",
+        "WC_CONSUMER_KEY": "ck_xxx",
+        "WC_CONSUMER_SECRET": "cs_xxx"
+      }
+    }
+  }
+}
+```
+
+Then ask things like *"What were last month's WooCommerce sales?"* or *"List the 5 most recent orders that are on hold."*
+
+## Articles (off-site)
+
+Field notes published on DEV (not duplicates of wppoland.com pages):
+
+- [A read-only MCP server for WooCommerce: what AI agents actually need from a store](https://dev.to/wppolandcom/a-read-only-mcp-server-for-woocommerce-what-ai-agents-actually-need-from-a-store-3fk6)
+- [Syncing a wholesaler's API into WooCommerce without overselling or melting the server](https://dev.to/wppolandcom/syncing-a-wholesalers-api-into-woocommerce-without-overselling-or-melting-the-server-38ao)
+- [Twelve months after migrating wppoland.com from WordPress to Astro on Cloudflare Pages](https://dev.to/wppolandcom/twelve-months-after-migrating-wppolandcom-from-wordpress-to-astro-on-cloudflare-pages-11fi)
+
+Show HN: [discussion](https://news.ycombinator.com/item?id=48815903)
+
+## Verify
+
+```bash
+npm run check   # builds, then asserts all five tools register (no network/credentials needed)
+```
+
+## Notes
+
+- Node 18+ (uses the built-in `fetch`).
+- Logs go to stderr so they never corrupt the stdio MCP protocol on stdout.
+- API errors are surfaced with the store's message; credentials are never echoed.
+
+## License
+
+MIT © [WPPoland](https://wppoland.com/en/)

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * woocommerce-mcp — a Model Context Protocol server for WordPress + WooCommerce.
+ *
+ * Gives Claude (and any MCP client) read access to a store over the public
+ * WordPress and authenticated WooCommerce REST APIs: products, single product,
+ * recent orders, a sales report, and blog posts. Read-only by design — it never
+ * writes to the store.
+ *
+ * Configure with env vars:
+ *   WP_URL              e.g. https://shop.example.com   (required)
+ *   WC_CONSUMER_KEY     WooCommerce REST API key        (required for wc_* tools)
+ *   WC_CONSUMER_SECRET  WooCommerce REST API secret     (required for wc_* tools)
+ *
+ * Built by wppoland.com — WordPress & WooCommerce engineering.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const VERSION = "0.1.0";
+export declare function createServer(): McpServer;

package/dist/index.js

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+/**
+ * woocommerce-mcp — a Model Context Protocol server for WordPress + WooCommerce.
+ *
+ * Gives Claude (and any MCP client) read access to a store over the public
+ * WordPress and authenticated WooCommerce REST APIs: products, single product,
+ * recent orders, a sales report, and blog posts. Read-only by design — it never
+ * writes to the store.
+ *
+ * Configure with env vars:
+ *   WP_URL              e.g. https://shop.example.com   (required)
+ *   WC_CONSUMER_KEY     WooCommerce REST API key        (required for wc_* tools)
+ *   WC_CONSUMER_SECRET  WooCommerce REST API secret     (required for wc_* tools)
+ *
+ * Built by wppoland.com — WordPress & WooCommerce engineering.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+export const VERSION = "0.1.0";
+/** Read + validate env at call time (not import time) so tooling/tests don't need credentials. */
+function loadConfig(requireWoo) {
+    const wpUrl = (process.env.WP_URL ?? "").trim().replace(/\/+$/, "");
+    if (!wpUrl)
+        throw new Error("Missing required env var WP_URL (e.g. https://shop.example.com)");
+    if (!/^https?:\/\//.test(wpUrl))
+        throw new Error("WP_URL must start with http:// or https://");
+    const key = (process.env.WC_CONSUMER_KEY ?? "").trim();
+    const secret = (process.env.WC_CONSUMER_SECRET ?? "").trim();
+    if (requireWoo && (!key || !secret)) {
+        throw new Error("This tool needs WC_CONSUMER_KEY and WC_CONSUMER_SECRET (WooCommerce > Settings > Advanced > REST API).");
+    }
+    return { wpUrl, key, secret };
+}
+async function apiGet(base, params) {
+    const url = new URL(base);
+    for (const [k, v] of Object.entries(params)) {
+        if (v !== undefined && v !== "")
+            url.searchParams.set(k, String(v));
+    }
+    let res;
+    try {
+        res = await fetch(url, { headers: { Accept: "application/json" } });
+    }
+    catch (e) {
+        throw new Error(`Network error reaching ${url.host}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (!res.ok) {
+        // Surface the API error message but never echo the credentials in the URL.
+        let detail = "";
+        try {
+            const body = (await res.json());
+            detail = body?.message ? ` — ${body.message}` : "";
+        }
+        catch {
+            /* ignore non-JSON error bodies */
+        }
+        throw new Error(`API ${res.status} ${res.statusText}${detail}`);
+    }
+    return res.json();
+}
+function wc(cfg, path, params = {}) {
+    return apiGet(`${cfg.wpUrl}/wp-json/wc/v3/${path}`, {
+        consumer_key: cfg.key,
+        consumer_secret: cfg.secret,
+        ...params,
+    });
+}
+function wp(cfg, path, params = {}) {
+    return apiGet(`${cfg.wpUrl}/wp-json/wp/v2/${path}`, params);
+}
+const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
+const fail = (e) => ({
+    content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }],
+    isError: true,
+});
+export function createServer() {
+    const server = new McpServer({ name: "woocommerce-mcp", version: VERSION });
+    server.registerTool("list_products", {
+        title: "List products",
+        description: "List or search WooCommerce products. Returns id, name, sku, price, stock status and permalink.",
+        inputSchema: {
+            search: z.string().optional().describe("Search term to filter products by name/sku"),
+            per_page: z.number().int().min(1).max(100).optional().describe("Results per page (default 10)"),
+            status: z.enum(["any", "draft", "pending", "private", "publish"]).optional().describe("Product status filter"),
+        },
+    }, async ({ search, per_page, status }) => {
+        try {
+            const cfg = loadConfig(true);
+            const data = (await wc(cfg, "products", { search, per_page: per_page ?? 10, status }));
+            return ok(data.map((p) => ({
+                id: p.id, name: p.name, sku: p.sku, price: p.price,
+                stock_status: p.stock_status, permalink: p.permalink,
+            })));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("get_product", {
+        title: "Get product",
+        description: "Get a single WooCommerce product by id, with full details.",
+        inputSchema: { id: z.number().int().positive().describe("Product id") },
+    }, async ({ id }) => {
+        try {
+            return ok(await wc(loadConfig(true), `products/${id}`));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("list_orders", {
+        title: "List orders",
+        description: "List recent WooCommerce orders, newest first. Optionally filter by status.",
+        inputSchema: {
+            per_page: z.number().int().min(1).max(100).optional().describe("Results per page (default 10)"),
+            status: z
+                .enum(["any", "pending", "processing", "on-hold", "completed", "cancelled", "refunded", "failed"])
+                .optional()
+                .describe("Order status filter"),
+        },
+    }, async ({ per_page, status }) => {
+        try {
+            const cfg = loadConfig(true);
+            const data = (await wc(cfg, "orders", { per_page: per_page ?? 10, status, orderby: "date", order: "desc" }));
+            return ok(data.map((o) => ({
+                id: o.id, number: o.number, status: o.status, total: o.total, currency: o.currency,
+                date_created: o.date_created, customer: o.billing?.email,
+            })));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("sales_report", {
+        title: "Sales report",
+        description: "WooCommerce sales totals for a period (week, month, last_month, year). Gross sales, orders, items.",
+        inputSchema: {
+            period: z.enum(["week", "month", "last_month", "year"]).optional().describe("Reporting period (default week)"),
+        },
+    }, async ({ period }) => {
+        try {
+            return ok(await wc(loadConfig(true), "reports/sales", { period: period ?? "week" }));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    server.registerTool("search_posts", {
+        title: "Search posts",
+        description: "Search published WordPress blog posts (public REST API, no WooCommerce keys required).",
+        inputSchema: {
+            search: z.string().min(1).describe("Search term"),
+            per_page: z.number().int().min(1).max(50).optional().describe("Results per page (default 10)"),
+        },
+    }, async ({ search, per_page }) => {
+        try {
+            const cfg = loadConfig(false);
+            const data = (await wp(cfg, "posts", { search, per_page: per_page ?? 10, _fields: "id,link,title,date,excerpt" }));
+            return ok(data.map((p) => ({
+                id: p.id, link: p.link, date: p.date,
+                title: p.title?.rendered,
+            })));
+        }
+        catch (e) {
+            return fail(e);
+        }
+    });
+    return server;
+}
+async function main() {
+    const server = createServer();
+    await server.connect(new StdioServerTransport());
+    // stdio transport: logs must go to stderr so they don't corrupt the protocol on stdout.
+    console.error(`woocommerce-mcp v${VERSION} ready (stdio)`);
+}
+// Only start the stdio server when run directly, not when imported (tests import createServer).
+const invokedDirectly = process.argv[1] && import.meta.url === `file://${process.argv[1]}`;
+if (invokedDirectly) {
+    main().catch((err) => {
+        console.error(err);
+        process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@wppoland/woocommerce-mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol (MCP) server for WordPress and WooCommerce. Gives Claude and other AI agents read access to products, orders, sales reports and posts over the REST API.",
+  "type": "module",
+  "mcpName": "io.github.wppoland/woocommerce-mcp",
+  "bin": {
+    "woocommerce-mcp": "dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wppoland/woocommerce-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/wppoland/woocommerce-mcp/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "npm run build && node test/smoke.mjs",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "wordpress",
+    "woocommerce",
+    "claude",
+    "ai-agents",
+    "rest-api"
+  ],
+  "author": "wppoland.com",
+  "homepage": "https://wppoland.com/en/",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.0",
+    "typescript": "^5.6.0"
+  }
+}