Metadata-Version: 2.4
Name: clariq-mcp
Version: 1.1.0
Summary: Model Context Protocol (MCP) server that connects WooCommerce store analytics to AI assistants.
Author: Clariq
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/clariqapp/mcp-server
Project-URL: Repository, https://github.com/clariqapp/mcp-server
Project-URL: Issues, https://github.com/clariqapp/mcp-server/issues
Keywords: woocommerce,mcp,model-context-protocol,analytics,ecommerce
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24.0; extra == "dev"
Requires-Dist: anyio>=4.0.0; extra == "dev"
Requires-Dist: respx>=0.21.0; extra == "dev"
Dynamic: license-file

# 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.

[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0.html)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue)]()

---

## 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](https://github.com/clariqapp/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](https://github.com/clariqapp/plugin)), 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](https://docs.astral.sh/uv/):

```bash
uvx clariq-mcp
```

or install it with pipx/pip:

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

### 3. Add it to Claude Desktop

Edit `claude_desktop_config.json`:

```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

| Tool | What it answers |
|------|-----------------|
| `get_sales_performance` | Revenue, orders, tax, net and AOV — as a summary or hourly/daily/monthly trend (`interval`) |
| `get_product_analytics` | Top products/variations by net revenue, items bought together, or a product catalog (`mode`) |
| `get_customer_insights` | Geographic breakdown by city/country, or first-time vs repeat cohorts (`dimension`) |
| `get_marketing_attribution` | UTM traffic sources, campaign leaderboard, or attribution coverage (`dimension`) |
| `get_technical_analytics` | Device, OS, or OS-by-payment-method breakdowns (`breakdown`) |
| `get_inventory_runway` | Days of stock left per product vs 30-day sales velocity |
| `get_coupon_leakage` | Coupon usage, discount given, and discount share of revenue (margin drain) |
| `get_repurchase_clock` | Repeat-buyer count and average/fastest/longest days between orders |

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.

| | **Local bridge** |
|---|---|
| Where data lives | Your WordPress database |
| Account needed | No |
| Query limits | None |
| Auth | HMAC bridge secret |

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

| Variable | Default | Description |
|---|---|---|
| `CLARIQ_WP_URL` | `http://localhost:8888` | Your WordPress site URL |
| `CLARIQ_BRIDGE_SECRET` | — | Bridge secret from the plugin settings |

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](https://github.com/clariqapp/mcp-server/issues/new).

## Development

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

See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues go to
[SECURITY.md](SECURITY.md) — **not** public issues.

## License

[AGPL-3.0-or-later](LICENSE) — 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.
