# NAND Commerce MCP Server

Model Context Protocol server for the NAND Commerce admin. It exposes **77 tools**
covering the whole admin surface — shops, products, variants, images, collections, pages,
blogs, posts, datasets, customers, orders, invoices, shipments, discounts, checkout
sessions, email templates, media uploads and Shopify imports.

- Endpoint: `https://mcp.nand-studios.com/mcp` (Streamable HTTP, JSON-RPC 2.0 over POST)
- Server: `nand-commerce` v1.0.0
- Protocol versions: 2025-06-18, 2025-03-26, 2024-11-05
- Backing API: `https://main-api.shop.nand-studios.com`

## Connect

```json
{
  "mcpServers": {
    "nand-commerce": {
      "type": "http",
      "url": "https://mcp.nand-studios.com/mcp"
    }
  }
}
```

Claude Code: `claude mcp add --transport http nand-commerce https://mcp.nand-studios.com/mcp`

## Authentication

Login goes through the admin panel API — the same email and password you use on
admin.nand-studios.com.

1. `login` with `{ "email": "...", "password": "..." }`.
2. The server stores the resulting admin session against your MCP session id, so
   later tool calls need nothing extra.
3. If your client does not preserve `Mcp-Session-Id`, pass the `session_token`
   returned by `login` as an argument to any tool.
4. Machine access: send `Authorization: Bearer <IMPORT_API_KEY>` on the HTTP request
   instead of logging in at all.

`whoami` tells you whether the current session is live; `logout` ends it.

## Conventions

- Inputs are strict: unknown arguments are rejected, required ones enforced.
- List tools return `{ "items": [...], "count": n }`; single-record tools return the record.
- Update tools merge — send only the fields you want to change. Two exceptions replace
  wholesale: `collection_update.product_ids` and `dataset_update.fields_json`.
- Money is in major units (e.g. `63` = 63 EUR). Booleans from list endpoints may arrive as `0`/`1`.
- Errors come back as tool errors with a `code` and `message`, not as protocol failures.

## Tools

| Tool | What it does | Arguments (**required**) | Kind |
| --- | --- | --- | --- |
| `login` | Sign in to the admin panel | **email**, **password** | write |
| `whoami` | Show the signed-in admin user | — | read-only |
| `logout` | End the admin session | — | write |
| `shops_list` | List shops | — | read-only |
| `shop_get` | Get one shop | **shop_id** | read-only |
| `shop_create` | Create a shop | **name**, slug, currency, locale, supportEmail | write |
| `shop_update` | Update a shop | **shop_id**, name, slug, status, default_currency, default_locale, storefront_url, email_sender_name, email_sender_address, support_email, policy_shipping_html, policy_returns_html, policy_privacy_html, tax_enabled | destructive |
| `shop_theme_get` | Get the checkout theme | **shop_id** | read-only |
| `shop_theme_update` | Update the checkout theme | **shop_id**, logoUrl, iconUrl, colorBackground, colorSurface, colorText, colorTextMuted, colorPrimary, colorPrimaryText, colorBorder, radiusSm, radiusMd, radiusLg, fontFamily, shadowCard | destructive |
| `products_list` | List products | shop_id | read-only |
| `product_get` | Get one product | **product_id** | read-only |
| `product_create` | Create a product | **shop_id**, **title**, handle, description_html, status, seo_title, seo_description, custom_fields_json, category, product_type, vendor, tags_json, theme_template, collection_ids | write |
| `product_update` | Update a product | **product_id**, title, handle, status, description_html, seo_title, seo_description, custom_fields_json, category, product_type, vendor, tags_json, theme_template, collection_ids | write |
| `product_delete` | Delete a product | **product_id** | destructive |
| `products_bulk_update` | Bulk update products | **updates** | write |
| `products_bulk_delete` | Bulk delete products | **ids** | destructive |
| `product_image_add` | Attach an image to a product | **product_id**, **bucket_key**, asset_id, alt, sort_order | write |
| `product_image_update` | Update a product image | **product_id**, **image_id**, alt, sort_order | write |
| `product_image_delete` | Remove a product image | **product_id**, **image_id** | destructive |
| `variant_create` | Add a variant to a product | **product_id**, title, sku, barcode, price, compare_at_price, inventory_quantity, max_buy_quantity, requires_shipping, weight, options_json, custom_field_overrides_json | write |
| `variant_update` | Update a variant | **variant_id**, title, sku, barcode, price, compare_at_price, inventory_quantity, max_buy_quantity, requires_shipping, weight, options_json, custom_field_overrides_json | write |
| `variant_delete` | Delete a variant | **variant_id** | destructive |
| `collections_list` | List collections | shop_id | read-only |
| `collection_get` | Get one collection | **collection_id** | read-only |
| `collection_create` | Create a collection | **shop_id**, **title**, handle, description_html, custom_fields_json, product_ids | write |
| `collection_update` | Update a collection | **collection_id**, title, handle, description_html, custom_fields_json, product_ids | destructive |
| `collection_delete` | Delete a collection | **collection_id** | destructive |
| `collections_bulk_update` | Bulk update collections | **updates** | write |
| `collections_bulk_delete` | Bulk delete collections | **ids** | destructive |
| `pages_list` | List pages | **shop_id** | read-only |
| `page_get` | Get one page | **page_id** | read-only |
| `blogs_list` | List blogs | shop_id | read-only |
| `blog_get` | Get one blog | **blog_id** | read-only |
| `blog_create` | Create a blog | **shop_id**, **title**, handle, description_html, description_json, custom_fields_json, image_asset_id, image_url, image_alt, seo_title, seo_description, status, sort_order | write |
| `blog_update` | Update a blog | **blog_id**, title, handle, description_html, description_json, custom_fields_json, image_asset_id, image_url, image_alt, seo_title, seo_description, status, sort_order | write |
| `blog_delete` | Delete a blog | **blog_id** | destructive |
| `blog_posts_list` | List the posts of one blog | **blog_id** | read-only |
| `blog_posts_search` | Search blog posts across blogs | shop_id, blog_id | read-only |
| `blog_post_get` | Get one blog post | **post_id** | read-only |
| `blog_post_create` | Create a blog post | **blog_id**, **title**, handle, excerpt, content_html, content_json, custom_fields_json, image_asset_id, image_url, image_alt, author_name, tags_json, seo_title, seo_description, status, published_at | write |
| `blog_post_update` | Update a blog post | **post_id**, title, handle, excerpt, content_html, content_json, custom_fields_json, image_asset_id, image_url, image_alt, author_name, tags_json, seo_title, seo_description, status, published_at | write |
| `blog_post_delete` | Delete a blog post | **post_id** | destructive |
| `datasets_list` | List datasets | shop_id | read-only |
| `dataset_get` | Get one dataset | **dataset_id** | read-only |
| `dataset_create` | Create a dataset | **shop_id**, **name**, handle, description, status, fields_json | write |
| `dataset_update` | Update a dataset | **dataset_id**, name, handle, description, status, fields_json | destructive |
| `dataset_delete` | Delete a dataset | **dataset_id** | destructive |
| `customers_list` | List customers | — | read-only |
| `customer_get` | Get one customer | **customer_id** | read-only |
| `orders_list` | List orders | — | read-only |
| `order_get` | Get one order | **order_id** | read-only |
| `order_resend_confirmation` | Resend the order confirmation email | **order_id** | destructive |
| `order_create_shipment` | Create a shipment and notify the customer | **order_id**, **tracking_number** | destructive |
| `order_send_invoice` | Email the invoice to the customer | **order_id** | destructive |
| `order_verify_stripe_payment` | Verify an order's payment against Stripe | **order_id** | write |
| `order_invoice_get` | Get an order's invoice PDF | **order_id**, include_pdf_base64 | read-only |
| `discounts_list` | List discount codes | **shop_id** | read-only |
| `discount_create` | Create a discount code | **shop_id**, **code**, **type**, **value**, starts_at, ends_at, usage_limit, minimum_amount, active | write |
| `discount_update` | Update a discount code | **discount_id**, code, type, value, starts_at, ends_at, usage_limit, minimum_amount, active | write |
| `discount_delete` | Delete a discount code | **discount_id** | destructive |
| `checkout_session_create` | Create a checkout session for a cart | **cart_token**, email | write |
| `checkout_session_complete` | Complete a checkout session into an order | **session_id** | destructive |
| `email_templates_list` | List email templates | **shop_id** | read-only |
| `email_template_get` | Get one email template | **template_id** | read-only |
| `email_template_update` | Update an email template | **template_id**, subject_template, html_template, text_template, preview_data_json, enabled | destructive |
| `email_template_preview` | Render an email template preview | **template_id**, subject_template, html_template, text_template, preview_data_json | read-only |
| `email_template_test` | Render an email template with its stored preview data | **template_id** | read-only |
| `media_list` | List media assets | **shop_id** | read-only |
| `media_delete` | Delete a media asset | **asset_id** | destructive |
| `asset_sign_upload` | Create an upload slot | **shop_id**, **file_name**, content_type, resource_type, resource_id | write |
| `asset_upload` | Upload bytes into an upload slot | **upload_token**, source_url, content_base64, content_type | write |
| `media_upload_from_url` | Upload a file from a URL in one step | **shop_id**, **source_url**, file_name, content_type, resource_type, resource_id | write |
| `shopify_import_runs_list` | List Shopify import runs | **shop_id** | read-only |
| `shopify_import_records_list` | List Shopify import records | **shop_id**, resource_type, limit | read-only |
| `shopify_import_apply` | Apply a Shopify import bundle | **shop_id**, **bundle**, mode | destructive |
| `seed_shop` | Seed a demo shop | — | destructive |
| `seed_product` | Seed a demo product | — | destructive |

## Related

- Public storefront guide for agents: `https://shop-api.nand-studios.com/v1/agent.md`