Clariq MCP Server

Talk to your WooCommerce store. This MCP server connects AI assistants (Claude Desktop and any MCP-compatible client) to your store's analytics — sales performance, product margins, customer retention, and more.

Self-hosted and free: in local bridge mode your store data never leaves your own infrastructure. No account, no quota, no lock-in.

How it works

Claude Desktop ──(stdio)──> clariq-mcp ──(HMAC-signed HTTPS)──> your WordPress site
   (your machine)            (your machine)                     (Clariq plugin + WooCommerce DB)

• The MCP server runs on your machine as a local stdio process — it is never exposed to the internet.
• The Clariq WooCommerce plugin exposes two HMAC-authenticated REST endpoints (/wp-json/mcp-bridge/v1/*) and computes analytics against your own database on request.
• Result: ask Claude "How did sales do this month?" and get real numbers — without shipping your order data anywhere.

Quickstart (5 minutes)

1. Install the WordPress plugin

Install the Clariq plugin on your WooCommerce store (releases), then in wp-admin → Clariq settings choose Local Bridge mode. Copy the bridge secret shown there.

2. Install the MCP server

Requires Python 3.11+. Either run it directly with uv:

uvx clariq-mcp

or install it with pipx/pip:

pipx install clariq-mcp   # or: pip install clariq-mcp

3. Add it to Claude Desktop

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "clariq": {
      "command": "clariq-mcp",
      "env": {
        "CLARIQ_WP_URL": "https://your-store.com",
        "CLARIQ_BRIDGE_SECRET": "your-bridge-secret"
      }
    }
  }
}

Restart Claude Desktop. Done — ask it a question about your store.

Tools

Most tools take an optional start_date/end_date (YYYY-MM-DD) plus the view selector shown in parentheses; sensible defaults apply when omitted.

How it connects

This server talks to your store through the Clariq plugin's local bridge — a WordPress REST endpoint authenticated with an HMAC bridge secret. Your data stays in your WordPress database; nothing is sent to Clariq's cloud.

Prefer a fully hosted, always-on endpoint (no self-hosting, connect any MCP client by URL)? That's Clariq's hosted MCP gateway — a separate paid service at mcp.clariqapp.com/<slug>/mcp — not this package.

Configuration reference

All settings can come from the environment or a .env file (see .env.example).

Troubleshooting

• mcp_bridge_disabled (403): the plugin is not in Local Bridge mode.
• 401 on every call: the bridge secret doesn't match — copy it again from the plugin settings page.
• 404 on /wp-json/mcp-bridge/v1/ping: the plugin isn't active, or permalinks are disabled (pretty permalinks are required).
• More help: open a connection troubleshooting issue.

Development

pip install -e ".[dev]"
pytest tests/ -v

See CONTRIBUTING.md. Security issues go to SECURITY.md — not public issues.

License

AGPL-3.0-or-later — free to use, self-host, and modify. If you offer this software as a hosted service, you must share your changes under the same license.