In beta. Behavior subject to change.

Readme

bermooda MCP

Your shop, ready for agents

@bermooda/mcp gives Cursor, Claude, and any MCP client typed tools for settings, catalog, orders, and reports. Every call goes through the Admin API.

npx -y @bermooda/mcp

Node.js ≥ 22.22 · stdio or HTTP · MIT licensed

agent@bermooda/mcp
› Is my shop connected?
⏺ ping
⎿ ✔ Connected to http://localhost:3000
⎿ store "Demo Shop" · currency EUR · locale en
# URL and berm_ key verified against /api/admin/v1

What it does

The admin, in your agent's hands.

Tools are grouped by intent, not one per route. An agent can set up a shop, keep the catalog current, and answer "how did we do last week" without you opening the admin or writing a line against the Admin REST API.

  • ping · setup_shop

    Stand up a store

    Verify the connection, then set name, currencies, shipping, categories, products, and theme in one planned call.

  • get_settings · update_settings

    Tune settings

    Read the full settings snapshot or patch one section: general, currencies, locales, tax, shipping, SEO.

  • upsert_product · import_products_csv

    Run the catalog

    List, create, update, and delete products and categories, or bulk import a CSV after a local dry run.

  • list_orders · update_order_status

    Work the orders

    Page through orders, open one, and move it along. Cancelling or refunding asks for confirmation.

  • activate_theme · update_plugins

    Shape the storefront

    List installed themes and plugins, switch the active theme, and enable, reorder, or configure plugins.

  • get_overview_kpis · get_top_products

    Read the numbers

    Revenue, AOV, conversion, top products, customers, low stock, and export health for any date range.

Connect

One config block. Any client.

The server needs two things: where your shop lives and a berm_ key. The CLI writes both for Cursor. Claude Desktop and other clients take the same block.

  1. 01

    Install a shop with bermooda install

  2. 02

    Run bermooda mcp init, or paste the config block

  3. 03

    Restart Cursor or Claude Desktop

  4. 04

    Ask the agent to call ping

mcp.jsonCursor · Claude Desktop
{
  "mcpServers": {
    "bermooda": {
      "command": "npx",
      "args": ["-y", "@bermooda/mcp"],
      "env": {
        "BERMOODA_URL": "http://localhost:3000",
        "BERMOODA_API_KEY": "berm_…"
      }
    }
  }
}
terminal@bermooda/cli
# from your shop directory
$ bermooda mcp init
✔ Wrote MCP config to ~/my-shop/.cursor/mcp.json
environment
  • BERMOODA_URL

    Shop origin, e.g. http://localhost:3000

  • BERMOODA_API_KEY

    Admin API key, starts with berm_

  • PORT

    HTTP transport listen port (default 8787)

Guardrails

Plan first. Confirm to commit.

Agents are fast and occasionally wrong. Tools that change a lot show their plan, and tools that can't be undone ask twice.

  • dryRunBulk changes

    setup_shop returns its plan and import_products_csv checks the CSV first. Nothing is written until the agent comes back with confirm.

  • confirmDestructive calls

    Deletes, cancellations, refunds, disabling plugins, and uploads refuse to run without an explicit confirm=true.

  • scopesAPI key

    Keys carry granular scopes like products:write, with admin as a super-scope. Every mutation is audited as api_key.

agentplan, then apply
⏺ setup_shop(dryRun: true)
{
  "settingsSections": ["general", "currencies", "shipping"],
  "categoriesCount": 2,
  "productsCount": 6,
  "themeId": "default"
}
⏺ delete_product(id: "prod_8f2k")
! Refusing delete product prod_8f2k: pass confirm=true
⏺ delete_product(id: "prod_8f2k", confirm: true)
✔ Deleted
httpPORT=8787
# for cloud agents that can't spawn a local process
$ BERMOODA_URL=https://shop.example.com \
  BERMOODA_API_KEY=berm_… npm run start:http
# listening on http://0.0.0.0:8787/mcp

$ curl http://localhost:8787/health
{ "ok": true, "name": "@bermooda/mcp", "version": "0.1.0" }

Transports

Local by default. Hosted when you need it.

Run it next to your editor over stdio, or start the Streamable HTTP server for agents that live in the cloud. Same tools either way.

  • stdioDefault

    Your client spawns the server with npx. Credentials live in the client config and never leave your machine.

  • Streamable HTTPHosted

    POST /mcp, stateless, one session per request. The key stays in the server process, not in each request.

Architecture

A thin layer. No side doors.

The server holds no domain logic and never touches the database. It calls the same Admin API as the admin UI, with the same scopes, so what an agent can do is exactly what its key allows.

request path
  1. 01Cursor · Claude

    native tools

  2. 02@bermooda/mcp

    HTTP Bearer berm_ key

  3. 03/api/admin/v1

    app/core

Reference

Every tool.

Arguments in the README →
Setup
  • ping

    Verify URL and API key

  • get_setup_status

    Bootstrap status

  • setup_shop

    Settings, categories, products, and theme in one call

  • get_settings · update_settings

    Read the snapshot or patch one section

Catalog
  • list_products · get_product

    Paginated list, or one product by id

  • upsert_product · delete_product

    Create, update, or delete a product

  • list_categories · get_category

    Category tree, or one category by id

  • create_category · update_category · delete_category

    Manage categories

  • import_products_csv

    Bulk import from CSV

Orders & inventory
  • list_orders · get_order

    Paginated orders, or one order in detail

  • update_order_status

    Move an order to a new status

  • list_inventory_locations

    Locations with inventory levels

  • set_inventory_level

    Set a variant quantity at a location

Storefront & integrations
  • list_themes · activate_theme

    Switch the active theme or save its settings

  • list_plugins · update_plugins

    Enable, disable, reorder, and configure plugins

  • *_webhook_subscription

    List, get, create, update, and delete webhooks

  • upload_media

    Upload a file to shop media storage

Reports
  • get_overview_kpis · get_sales_over_time

    Revenue, orders, AOV, conversion, daily sales

  • get_top_products · get_sales_by_category

    What sells, and where

  • get_customer_metrics · get_inventory_metrics

    New vs. returning, low and out of stock

  • get_ops_metrics · get_export_metrics

    Abandoned checkouts, export health

  • get_dashboard_report

    The full composed analytics payload

Resources
  • bermooda://settings

    Settings snapshot

  • bermooda://catalog/summary

    First product page and the category tree

Three lines to an agent-ready shop.

Install, write the config, restart your editor. Then ask your agent to ping.

terminalNode.js ≥ 24
$ npm i -g @bermooda/cli@latest
$ bermooda install
$ cd bermooda && bermooda mcp init
Agents guideAPI keys