Official bermooda MCP

MCP server for bermooda shops. Thin facade over the Admin REST API (/api/admin/v1) for Cursor, Claude Desktop, and other MCP clients.

Package: @bermooda/mcp
Phase: C + D — setup orchestration, themes/plugins, webhooks, media, inventory, Streamable HTTP (agent-integration.md)

Requirements

• Node.js ≥ 22.22.0
• A running bermooda shop + Admin API key (berm_…)

Configure

| Variable | Description | | ------------------ | ------------------------------------------- | | BERMOODA_URL | Shop origin, e.g. http://localhost:5173 | | BERMOODA_API_KEY | Admin-scoped API key (berm_…) | | PORT | HTTP transport listen port (default 8787) |

Keys come from CLI/seed bootstrap or Admin UI (see bermooda docs/api.md).

Cursor

Add to Cursor MCP settings (or project .cursor/mcp.json):

{
  "mcpServers": {
    "bermooda": {
      "command": "npx",
      "args": ["-y", "@bermooda/mcp"],
      "env": {
        "BERMOODA_URL": "http://localhost:5173",
        "BERMOODA_API_KEY": "berm_REPLACE_ME"
      }
    }
  }
}

Local checkout (no publish):

{
  "mcpServers": {
    "bermooda": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mcp/src/index.js"],
      "env": {
        "BERMOODA_URL": "http://localhost:5173",
        "BERMOODA_API_KEY": "berm_REPLACE_ME"
      }
    }
  }
}

See examples/cursor.mcp.json and examples/cursor.mcp.local.json.

Claude Desktop

Merge examples/claude_desktop_config.json into Claude Desktop’s claude_desktop_config.json (same command / env shape as Cursor).

Tools

| Tool | Purpose | | ----------------------------- | ------------------------------------------------------------------------------------- | | ping | Verify URL + API key (loads settings) | | get_setup_status | Bootstrap status (/setup) | | get_settings | Full settings snapshot | | update_settings | PATCH one settings section | | setup_shop | Orchestrate settings + categories + products/CSV + theme (dryRun or confirm=true) | | list_products | Paginated product list | | get_product | Product by id | | upsert_product | Create (no id) or update (with id) | | delete_product | Delete product (confirm=true) | | list_categories | Category tree | | get_category | Category by id | | create_category | Create category | | update_category | Update category | | delete_category | Recursive delete (confirm=true) | | list_orders | Paginated orders | | get_order | Order detail | | update_order_status | Set status (cancelled/refunded need confirm) | | import_products_csv | CSV import (confirm=true; optional local dryRun) | | list_themes | Registered themes + active theme | | activate_theme | Activate theme and/or save theme settings | | list_plugins | Registered plugins + enabled ids/order | | update_plugins | Enable/disable, reorder, settings (confirm when disabling) | | list_webhook_subscriptions | Paginated webhook subscriptions | | get_webhook_subscription | Subscription + recent deliveries | | create_webhook_subscription | Create subscription | | update_webhook_subscription | Update subscription | | delete_webhook_subscription | Delete subscription (confirm=true) | | upload_media | Multipart media upload (confirm=true) | | list_inventory_locations | Locations with inventory levels | | set_inventory_level | Set variant quantity at a location | | get_overview_kpis | Revenue, orders, AOV, conversion for a range | | get_sales_over_time | Daily sales buckets | | get_top_products | Top products by revenue | | get_sales_by_category | Revenue by category | | get_ops_metrics | Abandoned checkouts, recent orders, low stock | | get_dashboard_report | Full composed analytics payload | | get_customer_metrics | New/returning customers, order split, top spenders | | get_inventory_metrics | Low/out-of-stock snapshot, stock value, by location | | get_export_metrics | Scheduled export counts, recent runs, failure rate |

Resources

| URI | Description | | ---------------------------- | ---------------------------------- | | bermooda://settings | Settings snapshot | | bermooda://catalog/summary | First product page + category tree |

Develop

npm install
npm test
npm start        # stdio server (default); needs env vars
npm run start:http   # Streamable HTTP on PORT (default 8787)

Inspector (stdio):

npx @modelcontextprotocol/inspector node ./src/index.js

Streamable HTTP

For cloud agents or clients that cannot spawn a local stdio process, run the Streamable HTTP transport:

BERMOODA_URL=http://localhost:5173 BERMOODA_API_KEY=berm_… npm run start:http

• Endpoint: POST http://localhost:8787/mcp (stateless; one MCP session per request)
• Health: GET http://localhost:8787/health

Point MCP clients that support Streamable HTTP at the /mcp URL with the same bermooda env vars loaded in the server process (credentials are not passed per request).

Architecture

Cursor / Claude  --stdio or HTTP-->  @bermooda/mcp  --HTTP Bearer-->  /api/admin/v1

No Prisma or shop DB access from this process. Domain logic stays in the bermooda app.

License

MIT