How do I use gomag-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gomag-mcp show me orders placed today" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

gomag-mcp

by florinel-chis

Overview Schema Source Related Servers Discussions Admin

Python

Remote

gomag-mcp

A production-ready Model Context Protocol (MCP) server for the Gomag Public API, giving AI assistants like Claude direct, audited access to your Gomag e-commerce store.

Gomag is a Romanian e-commerce platform. This server exposes its entire public REST API as 48 typed MCP tools across 10 categories — from product and order management to shipping (AWB), invoicing, and loyalty points.

Features

48 MCP tools covering every Gomag Public API endpoint
Full structured audit logging — every tool call produces an immutable JSON Lines record (file + stderr)
Sensitive-field redaction — passwords, tokens, and API keys are masked in logs
Rate-limit awareness — tracks Gomag's Leaky Bucket headers and backs off automatically on 429
Exponential back-off retry for transient 429 / 5xx failures (configurable retries and factor)
Connection pooling via httpx.AsyncClient (keep-alive, max connections)
Fully async — non-blocking from transport to tool handler
Two MCP resources — gomag://health and gomag://rate-limit for observability
Zero secrets in code — all credentials come from environment variables

Related MCP server: Saleor MCP Server

Requirements

Python ≥ 3.10
A Gomag store with Public API access enabled
Your API Key and Shop URL from the Gomag admin panel

Installation

From source (recommended while in beta)

git clone https://github.com/florinel-chis/gomag-mcp.git
cd gomag-mcp

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# Install
pip install -e .

Using pip (once published)

pip install gomag-mcp

Configuration

All configuration is via environment variables (prefix GOMAG_). Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Required

Variable	Description
`GOMAG_API_KEY`	Your Gomag API key (`Apikey` header) — from Admin → API Settings
`GOMAG_API_SHOP`	Your shop URL, e.g. `https://yourshop.gomag.ro` (`ApiShop` header)

Optional

Variable	Default	Description
`GOMAG_BASE_URL`	`https://api.gomag.ro`	Gomag API base URL
`GOMAG_USER_AGENT`	`GomagMCP/1.0`	Custom User-Agent (must not be `PostmanRuntime/…`)
`GOMAG_REQUEST_TIMEOUT`	`30.0`	HTTP timeout in seconds
`GOMAG_MAX_RETRIES`	`3`	Retry attempts for 429 / 5xx responses
`GOMAG_RETRY_BACKOFF_FACTOR`	`1.0`	Exponential back-off multiplier (seconds)
`GOMAG_AUDIT_LOG_FILE`	`gomag_audit.jsonl`	Path to the rotating JSON Lines audit log
`GOMAG_AUDIT_LOG_MAX_BYTES`	`10485760`	Max log file size before rotation (10 MB)
`GOMAG_AUDIT_LOG_BACKUP_COUNT`	`5`	Number of rotated backup files to keep
`GOMAG_AUDIT_LOG_TO_STDERR`	`true`	Also emit audit events to stderr

Integration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gomag": {
      "command": "gomag-mcp",
      "env": {
        "GOMAG_API_KEY": "your_api_key_here",
        "GOMAG_API_SHOP": "https://yourshop.gomag.ro"
      }
    }
  }
}

Claude CLI (`claude`)

# Run once to register
claude mcp add gomag -- gomag-mcp

# Or with environment variables inline
GOMAG_API_KEY=xxx GOMAG_API_SHOP=https://yourshop.gomag.ro gomag-mcp

Run manually

# With .env file in current directory
gomag-mcp

# Or explicit env vars
GOMAG_API_KEY=xxx GOMAG_API_SHOP=https://yourshop.gomag.ro gomag-mcp

Available Tools

Products (`/api/v1/product/`)

Tool	Method	Endpoint	Description
`product_list`	GET	`/read/json`	List products — filter by id, sku, category, brand, updated date, promo tag, language
`product_create`	POST	`/write/json`	Create products — supports multi-language names/descriptions and product variants
`product_update`	POST	`/patch/json`	Patch existing products by id or sku
`product_update_inventory`	POST	`/inventory/json`	Bulk-update price, special price, and stock levels
`product_delete`	POST	`/delete/json`	Delete products by id or sku

Categories (`/api/v1/category/`)

Tool	Method	Endpoint	Description
`category_list`	GET	`/read/json`	List categories — filter by id, parent, language
`category_create`	POST	`/write/json`	Create categories with multi-language names
`category_update`	POST	`/patch/json`	Patch existing categories
`category_delete`	POST	`/delete/json`	Delete empty categories

Orders (`/api/v1/order/`)

Tool	Method	Endpoint	Description
`order_list`	GET	`/read/json`	List orders — filter by id, number, status, date range, email, phone
`order_status_types`	GET	`/status/read/json`	Get all available order status types
`order_create`	POST	`/add/json`	Create an order with billing, shipping, products, and discounts
`order_update_status`	POST	`/status/json`	Change order status with optional customer notification
`order_add_note`	POST	`/note/add/json`	Attach a public or private note to an order
`order_add_file`	POST	`/file/add/json`	Attach a file (by URL) to an order

Customers (`/api/v1/customer/`)

Tool	Method	Endpoint	Description
`customer_list`	GET	`/read/json`	List customers — filter by id, email, phone, modified date
`customer_ordered_products`	GET	`/orderedproducts/json`	Products a customer has previously ordered
`customer_create`	POST	`/add/json`	Register a new customer account
`customer_update`	POST	`/update/json`	Update customer details
`customer_login`	POST	`/login/json`	Authenticate a customer
`customer_change_password`	POST	`/passwordchange/json`	Change customer password
`customer_password_recovery`	POST	`/passwordrecovery/json`	Trigger password recovery email
`customer_delete_request`	POST	`/deleterequest/json`	Submit GDPR account-deletion request

Shipping / AWB (`/api/v1/awb/`)

AWB = Air Waybill — the tracking/shipping label used by Romanian courier services.

Tool	Method	Endpoint	Description
`awb_carrier_list`	GET	`/carrier/read/json`	List configured courier/carrier integrations
`awb_list`	GET	`/read/json`	List AWB records — filter by order, tracking number, carrier
`awb_create`	POST	`/add/json`	Manually register an AWB tracking number
`awb_generate`	POST	`/generate/json`	Auto-generate an AWB via the carrier API
`awb_delete`	POST	`/delete/json`	Delete an AWB record
`awb_print`	POST	`/print/json`	Generate a printable shipping label
`awb_update_status`	POST	`/status/update/json`	Update AWB delivery status

Invoices (`/api/v1/invoice/`)

Tool	Method	Endpoint	Description
`invoice_create`	POST	`/add/json`	Register an invoice for an order
`invoice_generate`	POST	`/generate/json`	Auto-generate invoice using store settings
`invoice_cancel`	POST	`/cancel/json`	Cancel (void) an invoice

Attributes (`/api/v1/attribute/`)

Tool	Method	Endpoint	Description
`attribute_list`	GET	`/read/json`	List product attributes
`attribute_create`	POST	`/write/json`	Create attributes with multi-language names and values
`attribute_update`	POST	`/patch/json`	Patch existing attributes

Reviews (`/api/v1/review/`)

Tool	Method	Endpoint	Description
`review_list`	GET	`/read/json`	List reviews — filter by product, customer, approval status
`review_create`	POST	`/write/json`	Submit a product review (1–5 stars)

Wishlist (`/api/v1/wishlist/`)

Tool	Method	Endpoint	Description
`wishlist_list`	GET	`/read/json`	List a customer's saved products
`wishlist_add`	POST	`/add/json`	Add a product to a customer's wishlist
`wishlist_remove`	POST	`/delete/json`	Remove a product from a wishlist

Store Reference Data

Tool	Method	Endpoint	Description
`currency_list`	GET	`/api/v1/currency/read/json`	List configured currencies
`payment_list`	GET	`/api/v1/payment/read/json`	List payment methods
`brand_list`	GET	`/api/v1/brand/read/json`	List brands/manufacturers
`filter_list`	GET	`/api/v1/filter/read/json`	Filterable attributes for a category
`banner_list`	GET	`/api/v1/banner/read/json`	Promotional banners
`fidelity_read`	POST	`/api/v1/fidelity/read/json`	Customer loyalty points balance
`rulecart_add`	POST	`/api/v1/rulecart/add/json`	Create a shopping cart discount rule

MCP Resources

Two read-only resources are exposed for observability:

URI	Description
`gomag://health`	Server status, configured shop URL, and current rate-limit snapshot
`gomag://rate-limit`	Live rate-limit counters from the most recent API response

Audit Logging

Every tool call — success or failure — writes one JSON Lines record to gomag_audit.jsonl (and optionally stderr). The file rotates automatically at 10 MB (5 backups kept by default).

Log record schema

{
  "timestamp": "2026-03-27T10:00:00.123456+00:00",
  "level": "AUDIT",
  "event_type": "tool_call",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "tool_name": "product_list",
  "parameters": { "page": 1, "limit": 10 },
  "api_method": "GET",
  "api_path": "/api/v1/product/read/json",
  "http_status": 200,
  "duration_ms": 123.456,
  "success": true,
  "error_message": null,
  "rate_limit_remaining_read": 45,
  "rate_limit_remaining_write": 10
}

On error, event_type is "tool_error", success is false, and error_message contains the exception text.

Sensitive field redaction

The following parameter names are always replaced with ***REDACTED*** in audit records, regardless of case:

password · confirmpassword · apikey · api_key · token · secret · authorization

Rate Limiting

The Gomag API implements a Leaky Bucket algorithm applied per shop across all API access.

Response headers (present on every response until the limit is reached):

Header	Description
`Api-RateLimit-Read`	Read request processing rate (req/s, default 1)
`Api-RateLimit-Read-Burst`	Maximum read requests in a burst
`Api-RateLimit-Read-Remaining`	Read requests remaining before throttling
`Api-RateLimit-Write`	Write request processing rate (req/s, default 1)
`Api-RateLimit-Write-Burst`	Maximum write requests in a burst
`Api-RateLimit-Write-Remaining`	Write requests remaining before throttling

This server:

Parses all six headers after every request
Exposes the latest values via gomag://rate-limit
On a 429 response, waits at least 1 second before the first retry, then uses exponential back-off for subsequent retries
On 5xx responses, uses pure exponential back-off (factor × 2^attempt)

Gomag API Reference

The Gomag Public API is documented within the included Postman collection (Gomag Public API.postman_collection.json). Key details:

Authentication

All requests require the ApiShop header. Write operations (POST) additionally require the Apikey header.

ApiShop: https://yourshop.gomag.ro        # every request
Apikey:  your_api_key_here                # POST requests only
User-Agent: <custom value>                # must not be PostmanRuntime/…

Both values are obtained from your Gomag admin panel under Settings → API.

Request format

HTTP method	Parameters
`GET`	URL query string
`POST`	`multipart/form-data` with a single field `data` whose value is the JSON-serialised payload

Base URL

https://api.gomag.ro

Response format

All endpoints return JSON. Paginated list endpoints include:

{
  "total": 1250,
  "page": 1,
  "pages": 13,
  "items": [ ... ]
}

Multi-language fields

Products, categories, and attributes support localised names. Language codes follow ISO 639-1 (ro, en, hu, etc.) and are configured per shop:

{
  "name": {
    "ro": "Geacă softshell",
    "en": "Softshell jacket"
  }
}

Security

Password handling

The following tools accept plaintext passwords in their parameters:

Tool	Sensitive parameters
`customer_create`	`password`, `confirm_password`
`customer_login`	`password`
`customer_change_password`	`old_password`, `new_password`, `confirm_new_password`

Important notes:

Passwords are transmitted to the Gomag API over HTTPS. Never call these tools over an unencrypted connection.
Passwords are never written to audit logs — only the email field is logged for these calls.
Do not pass plaintext passwords to an AI assistant in contexts where chat history is persisted or shared.

Audit log security

The audit log file (gomag_audit.jsonl) contains API call metadata. Restrict file permissions appropriately.
The startup log prints the absolute path to the audit file — check this to confirm where logs are written.
.env files and *.jsonl log files are excluded from git via .gitignore.

Development

Running tests

pip install -e ".[dev]"
pytest

Tests use respx to mock HTTP responses — no live credentials required.

Project layout

src/gomag_mcp/
├── __init__.py       # package version
├── __main__.py       # enables `python -m gomag_mcp`
├── server.py         # FastMCP entry point, lifespan, resources
├── config.py         # Pydantic settings (GOMAG_* env vars)
├── audit.py          # Structured JSON audit logger
├── client.py         # Async HTTP client (retry, rate-limit, pooling)
├── context.py        # Shared AppContext (avoids circular imports)
└── tools/
    ├── product.py    # 5 tools
    ├── category.py   # 4 tools
    ├── order.py      # 6 tools
    ├── customer.py   # 8 tools
    ├── awb.py        # 7 tools
    ├── invoice.py    # 3 tools
    ├── attribute.py  # 3 tools
    ├── review.py     # 2 tools
    ├── wishlist.py   # 3 tools
    └── misc.py       # 7 tools

Adding a new tool

Find (or create) the appropriate module in src/gomag_mcp/tools/
Add a function inside the register(mcp) function decorated with @mcp.tool()
Call get_context() to access the shared GomagClient and AuditLogger
Wrap the API call with async with ctx.audit.tool_call(...) — all logging is automatic

@mcp.tool()
async def my_new_tool(param: str) -> dict[str, Any]:
    """Clear docstring — this becomes the tool description visible to Claude."""
    ctx = get_context()
    params = {"param": param}
    async with ctx.audit.tool_call("my_new_tool", params, "GET", "/api/v1/...") as ar:
        result = await ctx.client.get("/api/v1/...", params=params)
        ar.update(result)
        return result["data"]

License

Available Tools

48 tools

attribute_createA

Create one or more product attributes.

Parameters

data : JSON array of attribute objects. Each object may include: - name (dict, keyed by language e.g. {"ro": "Culoare", "en": "Color"}) - type (string) attribute type (e.g. "select", "text", "multiselect") - values (array of value objects, each with a localised "name" dict)

Example

'[{"name": {"ro": "Culoare", "en": "Color"}, "type": "select", "values": [{"name": {"ro": "Rosu", "en": "Red"}}, {"name": {"ro": "Albastru", "en": "Blue"}}]}]'

Inputs: data (required). Returns: object

attribute_listA

List product attributes defined in the store.

Parameters

id : Filter by specific attribute ID. page : Page number. limit : Results per page (1–100).

Inputs: id, page, limit. Returns: object

attribute_updateA

Update (patch) existing product attributes.

Parameters

data : JSON array of partial attribute objects. Must include "id" plus the fields to update.

Example

'[{"id": 5, "name": {"ro": "Marime", "en": "Size"}}]'

Inputs: data (required). Returns: object

awb_carrier_listA

Return the list of configured shipping carriers/couriers available in the store.

Inputs: no named parameters. Returns: object

awb_createA

Manually create an AWB record for an order.

Parameters

data : JSON object with AWB details. Key fields: - orderId (int) internal order ID - carrierId (int) carrier ID from awb_carrier_list() - awbNumber (string) tracking number issued by the carrier - packages (int) number of packages - weight (float) total shipment weight in kg

Example

'{"orderId": 100, "carrierId": 3, "awbNumber": "1Z999AA10123456784", "packages": 1, "weight": 1.5}'

Inputs: data (required). Returns: object

awb_deleteB

Delete an AWB record.

Parameters

awb_id : Internal AWB record ID.

Inputs: awb_id (required). Returns: object

awb_generateA

Generate an AWB automatically through the carrier's integrated API.

Parameters

data : JSON object with generation details. Key fields: - orderId (int) internal order ID - carrierId (int) carrier ID from awb_carrier_list() - packages (int) number of packages (default 1) - weight (float) total weight in kg

Example

'{"orderId": 100, "carrierId": 3, "packages": 1, "weight": 2.0}'

Inputs: data (required). Returns: object

awb_listA

List AWB (Air Waybill / tracking numbers) records.

Parameters

order_id : Filter by the order's internal ID. awb_number : Filter by specific AWB tracking number. carrier_id : Filter by carrier/courier ID. page : Page number. limit : Results per page (1–100).

Inputs: order_id, awb_number, carrier_id, page, +1 more. Returns: object

awb_printA

Generate a printable shipping label (PDF or similar) for an AWB.

Parameters

awb_id : Internal AWB record ID.

Returns a response typically containing a URL or base64-encoded label content.

Inputs: awb_id (required). Returns: object

awb_update_statusA

Update the delivery status of an AWB.

Parameters

awb_id : Internal AWB record ID. status : New status string (carrier-specific, e.g. "delivered", "in_transit", "returned"). update_order_status : If true, also update the parent order's status accordingly.

Inputs: awb_id (required), status (required), update_order_status. Returns: object

banner_listB

Return banners (promotional images/links) defined in the store.

Parameters

position : Filter by banner position/zone (store-defined key). page : Page number. limit : Results per page.

Inputs: position, page, limit. Returns: object

brand_listC

Return the list of brands (manufacturers) defined in the store.

Parameters

page : Page number. limit : Results per page (1–100).

Inputs: page, limit. Returns: object

category_createA

Create one or more categories.

Parameters

data : JSON array of category objects. Each object may include: - name (dict, keyed by language e.g. {"ro": "...", "en": "..."}) - description (dict, keyed by language) - parent_id (int, ID of parent category; omit or 0 for root) - enabled (0 or 1) - image (URL string)

Example

'[{"name": {"ro": "Electrocasnice", "en": "Appliances"}, "enabled": 1}]'

Inputs: data (required). Returns: object

category_deleteA

Delete categories. Only empty categories (no products, no sub-categories) can be deleted.

Parameters

data : JSON array of objects with "id" fields.

Example

'[{"id": 12}]'

Inputs: data (required). Returns: object

category_updateA

Update (patch) existing categories.

Parameters

data : JSON array of partial category objects. Must include "id" plus the fields to change.

Example

'[{"id": 12, "name": {"ro": "Electronice", "en": "Electronics"}}]'

Inputs: data (required). Returns: object

currency_listA

Return the list of currencies configured in the Gomag store.

Inputs: no named parameters. Returns: object

customer_change_passwordA

Change a customer's password.

Parameters

email : Customer e-mail address. old_password : Current password for verification (plain text — never logged). new_password : New password to set (plain text — never logged). confirm_new_password : Must match new_password.

Inputs: email (required), old_password (required), new_password (required), confirm_new_password (required). Returns: object

customer_createA

Create a new customer account.

Parameters

email : Customer e-mail address (unique). firstname : First name. lastname : Last name. password : Account password (plain text — only use over HTTPS; never logged). confirm_password : Must match password. phone : Optional phone number. newsletter : Subscribe to newsletter (true/false).

Inputs: email (required), firstname (required), lastname (required), password (required), +3 more. Returns: object

customer_delete_requestA

Submit a GDPR account-deletion request for a customer.

The customer will be flagged for deletion in the store's admin panel. This does NOT immediately delete the account.

Parameters

email : Customer e-mail address.

Inputs: email (required). Returns: object

customer_listA

List customers registered in the Gomag store.

Parameters

id : Filter by internal customer ID. email : Filter by e-mail address. phone : Filter by phone number. updated : Filter customers modified on/after this date (YYYY-MM-DD). page : Page number. limit : Results per page (1–100).

Inputs: id, email, phone, updated, +2 more. Returns: object

customer_loginA

Authenticate a customer and return session/token data.

Parameters

email : Customer e-mail address. password : Customer password (plain text — only use over HTTPS; never logged).

Returns the API response which typically includes a session token or authentication confirmation.

Inputs: email (required), password (required). Returns: object

customer_ordered_productsA

Get a list of products that a specific customer has ordered.

Parameters

customer_id : Internal customer ID. email : Customer e-mail (alternative to customer_id). page : Page number. limit : Results per page.

Inputs: customer_id, email, page, limit. Returns: object

customer_password_recoveryB

Trigger a password recovery e-mail for a customer.

Parameters

email : Customer e-mail address to send the recovery link to.

Inputs: email (required). Returns: object

customer_updateB

Update an existing customer's details.

Parameters

data : JSON object with customer fields to update. Must include "id" or "email" to identify the customer, plus the fields to change.

Example

'{"id": 123, "phone": "0721000001", "newsletter": false}'

Inputs: data (required). Returns: object

fidelity_readC

Retrieve a customer's fidelity (loyalty) points balance.

Parameters

customer_id : Customer's internal ID. email : Customer e-mail (alternative identifier).

Inputs: customer_id, email. Returns: object

invoice_cancelC

Cancel (void) an invoice.

Parameters

invoice_id : Internal invoice ID to cancel.

Inputs: invoice_id (required). Returns: object

invoice_createB

Create (register) an invoice for an order.

Parameters

data : JSON object with invoice details. Key fields: - orderId (int) internal order ID - number (string) invoice number/series - date (YYYY-MM-DD) invoice date - series (string) invoice series (e.g. "FCT") - dueDate (YYYY-MM-DD) payment due date (optional)

Example

'{"orderId": 100, "series": "FCT", "number": "0001234", "date": "2026-03-27"}'

Inputs: data (required). Returns: object

invoice_generateB

Auto-generate an invoice for an order using the store's configured invoicing settings.

Parameters

order_id : Internal order ID. series : Invoice series to use (optional; uses store default if omitted).

Inputs: order_id (required), series. Returns: object

order_add_fileA

Attach a file (by URL) to an order.

Parameters

order_id : Internal order ID. file_url : Publicly accessible URL of the file to attach. file_name : Display name for the file (optional, defaults to the URL filename).

Inputs: order_id (required), file_url (required), file_name. Returns: object

order_add_noteA

Add a note to an order.

Parameters

order_id : Internal order ID. note : Note text. is_public : If true the note is visible to the customer (default false).

Inputs: order_id (required), note (required), is_public. Returns: object

order_createA

Create a new order.

Parameters

data : JSON object describing the order. Key fields: - number (string) order reference number - date (YYYY-MM-DD) - payment (string) payment method key - currency (e.g. "RON") - shippingValue (string/number) - subtotal (string/number) - billing (object: lastname, firstname, address, city, region, country, phone, email) - shipping (object: same fields + zipcode) - products (array: sku, name, price, quantity, tax, weight) - discounts (array: name, voucher, value) — optional

Example

'{"number": "ORD-001", "date": "2026-03-27", "payment": "cod", "currency": "RON", "shippingValue": "20", "subtotal": "199.99", "billing": {"lastname": "Doe", "firstname": "John", "address": "Str. Test 1", "city": "Bucharest", "region": "Ilfov", "country": "Romania", "phone": "0721000000", "email": "john@example.com"}, "shipping": {"lastname": "Doe", "firstname": "John", "address": "Str. Test 1", "city": "Bucharest", "region": "Ilfov", "country": "Romania", "zipcode": "010101", "phone": "0721000000", "email": "john@example.com"}, "products": [{"sku": "PROD-1", "name": "Product", "price": "199.99", "quantity": "1", "tax": "19", "weight": "500"}]}'

Inputs: data (required). Returns: object

order_listB

List orders from the Gomag store.

Parameters

id : Filter by internal order ID. number : Filter by order number. status : Filter by status key (e.g. "sale", "return", "cancel"). date_from : Include orders placed on/after this date (YYYY-MM-DD). date_to : Include orders placed on/before this date (YYYY-MM-DD). email : Filter by customer e-mail. phone : Filter by customer phone number. page : Page number. limit : Results per page (1–100).

Inputs: id, number, status, date_from, +5 more. Returns: object

order_status_typesA

Return the list of available order status types defined in the store.

Inputs: no named parameters. Returns: object

order_update_statusA

Update the status of an existing order.

Parameters

order_id : Internal order ID. status : New status key (e.g. "sale", "return", "cancel"). Use order_status_types() to see available values. notify_customer : Send a notification e-mail to the customer (true/false). note : Optional internal note to attach to the status change.

Inputs: order_id (required), status (required), notify_customer, note. Returns: object

payment_listA

Return the list of payment methods available in the store.

Inputs: no named parameters. Returns: object

product_createA

Create one or more products.

Parameters

data : JSON array of product objects. Each object may include: - name (dict, keyed by language code e.g. {"ro": "...", "en": "..."}) - description (dict, keyed by language) - enabled (0 or 1) - vat (VAT percentage, e.g. 19) - currency (e.g. "RON") - brand (brand name string) - categories (array of category path arrays) - versions (array of variant objects with sku, price, stock, weight, ean, ...)

Example

'[{"name": {"ro": "Produs test", "en": "Test product"}, "enabled": 1, "vat": 19, "currency": "RON", "versions": [{"sku": "TEST-001", "price": 99.99, "stock": 10}]}]'

Inputs: data (required). Returns: object

product_deleteA

Delete products by SKU or ID.

Parameters

data : JSON array of objects identifying the products to delete. Each object should contain either "id" or "sku".

Example

'[{"sku": "TEST-001"}, {"id": 42}]'

Inputs: data (required). Returns: object

product_listA

List products from the Gomag store.

Parameters

page : Page number (pagination). limit : Results per page (1–100). id : Filter by internal product ID. sku : Filter by product SKU/code. category : Filter by category ID. brand : Filter by brand ID. updated : Filter products modified on/after this date (YYYY-MM-DD). add_versions : Include product variants/versions (true/false). include_files: Include attached files (true/false). include_videos: Include attached videos (true/false). promo_tag : Filter by promotional tag key (e.g. "new", "recommended"). view : Language code for localised fields (e.g. "ro", "en", "hu").

Inputs: page, limit, id, sku, +8 more. Returns: object

product_updateA

Update (patch) existing products.

Parameters

data : JSON array of partial product objects. Must include an identifier field (id or sku) plus the fields to update.

Example

'[{"sku": "TEST-001", "versions": [{"sku": "TEST-001", "price": 79.99}]}]'

Inputs: data (required). Returns: object

product_update_inventoryA

Bulk-update product price and/or stock (inventory sync).

Parameters

data : JSON array of inventory update objects, each containing: - sku (required) product SKU - price (optional) new price - stock (optional) new stock quantity - specialPrice (optional) discounted price

Example

'[{"sku": "TEST-001", "price": 89.99, "stock": 50}]'

Inputs: data (required). Returns: object

review_createB

Submit a product review.

Parameters

product_id : ID of the product being reviewed. rating : Star rating (1–5). title : Short review title/summary. content : Full review text. author_name : Reviewer's display name. author_email : Reviewer's e-mail address. approved : Set approval status immediately (true/false; defaults to store's moderation setting).

Inputs: product_id (required), rating (required), title (required), content (required), +3 more. Returns: object

review_listA

List product reviews.

Parameters

product_id : Filter by product ID. customer_id : Filter by customer ID. approved : Filter by approval status (true = approved only). page : Page number. limit : Results per page (1–100).

Inputs: product_id, customer_id, approved, page, +1 more. Returns: object

rulecart_addA

Create a shopping cart rule (discount / promotion).

Parameters

data : JSON object describing the cart rule. Key fields: - name (string) rule name - discount (float) discount amount or percentage - type (string) "fixed" | "percent" - code (string) voucher code (leave empty for auto-apply) - dateFrom (YYYY-MM-DD) start date (optional) - dateTo (YYYY-MM-DD) end date (optional) - usesPerCode (int) maximum total uses (0 = unlimited) - usesPerCustomer (int) maximum uses per customer (0 = unlimited) - enabled (0 or 1)

Example

'{"name": "Spring Sale 10%", "discount": 10, "type": "percent", "code": "SPRING10", "enabled": 1, "usesPerCode": 100}'

Inputs: data (required). Returns: object

wishlist_addC

Add a product to a customer's wishlist.

Parameters

customer_id : Customer's internal ID. product_id : Product's internal ID.

Inputs: customer_id (required), product_id (required). Returns: object

wishlist_listA

List a customer's saved (wishlist) products.

Parameters

customer_id : Customer's internal ID. email : Customer e-mail (alternative identifier). page : Page number. limit : Results per page (1–100).

Inputs: customer_id, email, page, limit. Returns: object

wishlist_removeB

Remove a product from a customer's wishlist.

Parameters

customer_id : Customer's internal ID. product_id : Product's internal ID.

Inputs: customer_id (required), product_id (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored 2026-06-12 12:50 across 48 tools

Disambiguation4/5

Most tools target distinct resources and actions, but there is potential confusion between pairs like awb_create vs awb_generate and invoice_create vs invoice_generate, which both create resources but differ in manual vs automatic mode. Descriptions help differentiate, but the overlaps could cause misselection by an agent.

Naming Consistency4/5

The vast majority of tools follow a consistent verb_noun pattern (e.g., attribute_create, awb_list, product_delete). However, a few deviate like fidelity_read (instead of fidelity_get or fidelity_list) and order_status_types (noun phrase instead of verb_noun). Overall, the pattern is clear and predictable.

Tool Count3/5

48 tools is on the high side, but the server covers a broad e-commerce domain (products, categories, customers, orders, shipping, invoices, reviews, etc.). Each tool serves a specific purpose, but the sheer number may feel unwieldy. It is justifiable given the scope, but borderline.

Completeness4/5

The tool set covers major CRUD operations for most entities (products, categories, customers, orders, reviews, wishlists, AWBs, invoices, etc.) and includes additional operations like inventory updates, status changes, and list tools. Minor gaps include no tool for managing carriers beyond listing, and no bulk update for product fields other than price/stock. Overall, the surface is largely complete for an e-commerce API.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

mcp
com.api2cart
Unified MCP server for 70+ eCommerce platforms: products, orders, customers, and more.
E-commerce & Retail CRM
1
https://mcp.api2cart.com/
mcpC
com.wix
A Model Context Protocol server for Wix AI tools
Developer Tools Content Management Systems App Automation
215
https://mcp.wix.com/mcp
Mercado Pago
com.mercadopago.mcp
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
Finance E-commerce & Retail App Automation
2
https://mcp.mercadopago.com/mcp
Apideck MCPA
dev.apideck.mcp
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Developer Tools
42
https://mcp.apideck.dev/mcp

Related MCP Servers

CS-Cart MCP Server
hungryweb
A
license
B
quality
D
maintenance
A Model Context Protocol server that provides comprehensive tools for managing CS-Cart e-commerce stores, enabling product management, order handling, and sales analytics.
Updated a year ago (2025-07-18 09:04 UTC)
12
4
MIT
Saleor MCP Server
ashwin2912
F
license
Not graded
quality
D
maintenance
A Model Context Protocol server that enables AI assistants to interact with Saleor e-commerce data including products, orders, customers, and more.
Updated a year ago (2025-07-20 03:43 UTC)
3
-
Shopify MCP
E-commerce & Retail Developer Tools
benwmerritt
A
license
Not graded
quality
B
maintenance
A Model Context Protocol server that connects AI agents to the Shopify Admin GraphQL API, enabling management of products, orders, customers, and more through natural language.
Updated 8 days ago (2026-11-05 23:37 UTC)
42 npm
6
MIT
shopify-admin-mcp
E-commerce & Retail
ChaseWNorton
A
license
Not graded
quality
D
maintenance
Production-grade MCP server for the Shopify Admin GraphQL API, exposing typed tools for AI agents to manage products, orders, customers, and more.
Updated 7 months ago (2026-04-03 08:50 UTC)
41 npm
MIT

gomag-mcp

Features

Requirements

Installation

From source (recommended while in beta)

Using pip (once published)

Configuration

Required

Optional

Integration

Claude Desktop

Claude CLI (claude)

Run manually

Available Tools

Products (/api/v1/product/)

Categories (/api/v1/category/)

Orders (/api/v1/order/)

Customers (/api/v1/customer/)

Shipping / AWB (/api/v1/awb/)

Invoices (/api/v1/invoice/)

Attributes (/api/v1/attribute/)

Reviews (/api/v1/review/)

Wishlist (/api/v1/wishlist/)

Store Reference Data

MCP Resources

Audit Logging

Log record schema

Sensitive field redaction

Rate Limiting

Gomag API Reference

Authentication

Request format

Base URL

Response format

Multi-language fields

Security

Password handling

Audit log security

Development

Running tests

Project layout

Adding a new tool

License

Available Tools

Parameters

Example

Parameters

Parameters

Example

Parameters

Example

Parameters

Parameters

Example

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Example

Parameters

Example

Parameters

Parameters

Example

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Parameters

Example

Parameters

Parameters

Parameters

Parameters

Example

Claude CLI (`claude`)

Products (`/api/v1/product/`)

Categories (`/api/v1/category/`)

Orders (`/api/v1/order/`)

Customers (`/api/v1/customer/`)

Shipping / AWB (`/api/v1/awb/`)

Invoices (`/api/v1/invoice/`)

Attributes (`/api/v1/attribute/`)

Reviews (`/api/v1/review/`)

Wishlist (`/api/v1/wishlist/`)