mintsoft-mcp

A Model Context Protocol server for the Mintsoft warehouse management system, so Claude and any other MCP-capable LLM client can look up orders, products, stock, inbound, returns and reports — and, if you deliberately enable it, make guarded changes.

Unofficial. Not affiliated with or endorsed by Mintsoft / Access Group.

Why the safety model matters

Mintsoft has no sandbox — every API key points at a live WMS. This server is built around that fact:

• Read-only by default. 37 read tools (GETs only). The 8 write tools are not registered at all unless MINTSOFT_ENABLE_WRITES=1 — when off, there is zero write surface for a model to misuse.
• Client allowlist. Even with writes on, every write is refused unless the target record belongs to a ClientId in MINTSOFT_WRITE_CLIENT_ALLOWLIST (default: empty = refuse everything). Point it at a dedicated test client account, not your real brands.
• Destructive ops double-gated. delete_product also requires confirm=True; amend_bundle refuses if the bundle has alt codes or recent stock activity unless force=True, and rolls back if the recreate fails.
• Everything audit-logged. Every API call (reads included) is appended to a local JSONL audit log (~/.mintsoft-mcp/mintsoft_api_audit.jsonl) — timestamp, method, path, body, status, affected id. The API key is never logged. Readable in-session via the get_api_audit_log tool for tracing or recovering from changes.

Install

From source (PyPI release coming):

uv tool install git+https://github.com/AhamadFalah/mintsoft-mcp
# or: pip install git+https://github.com/AhamadFalah/mintsoft-mcp

You need a Mintsoft API key (Mintsoft → Settings → API).

Hook it up

Claude Code

claude mcp add mintsoft -e MINTSOFT_API_KEY=your-key -- mintsoft-mcp

Claude Desktop / Cursor / Windsurf / VS Code — add to the client's MCP config (claude_desktop_config.json, .cursor/mcp.json, etc.):

{
  "mcpServers": {
    "mintsoft": {
      "command": "mintsoft-mcp",
      "env": { "MINTSOFT_API_KEY": "your-key" }
    }
  }
}

To enable writes (against a test client only — see safety model above):

"env": {
  "MINTSOFT_API_KEY": "your-key",
  "MINTSOFT_ENABLE_WRITES": "1",
  "MINTSOFT_WRITE_CLIENT_ALLOWLIST": "3"
}

Tools

Reads (37, always on)

Area	Tools
Orders	get_order, search_orders, get_order_id, list_orders, list_order_statuses, get_order_items, get_order_comments, track_order_by_tracking_number, list_order_channels
Products & stock	get_product, lookup_product_id, search_products, list_products, get_alt_codes, get_bundle, get_product_inventory, get_stock_levels_by_warehouse, get_stock_levels_updated_since, get_stock_flow, list_suppliers, precheck_discontinue
Inbound & returns	list_asns, get_asn, list_returns, get_return
Warehouse	list_warehouses, list_locations, list_warehouse_zones
Account & reference	list_clients, list_couriers, list_invoices, get_invoice, list_order_rules, run_report, get_ref_data
Meta	mintsoft_get (generic read-only GET passthrough for any endpoint not wrapped), get_api_audit_log

Writes (8, gated)

add_order_comment, add_order_tag, create_product, update_product, add_alt_code, delete_product (needs confirm=True), amend_bundle, discontinue_sku (footprint pre-check → rename [Discontinued] … + DisCont flag, same ProductId so history survives).

Baked-in Mintsoft API quirks

Things this server handles that the official docs don't tell you:

• Cloudflare blocks default user-agents (error 1010) — a browser UA is sent.
• Validation failures come back HTTP 200 with Success: false — surfaced as errors, not silently swallowed.
• Product.CommodityCode must be a nested object {"Code": "..."}; a plain string is silently dropped. The client coerces strings automatically.
• AltCodes POST takes query params, not a JSON body, and ConnectMappingType is a channel name string ("Amazon", "Shopify", "API"…) despite Swagger saying integer.
• Bundles are hidden from Product/Search — find them via Product/List or by id.
• There is no in-place bundle edit — amend_bundle does delete + recreate (new ProductId) with guards and rollback.

Configuration

Env var	Default	Purpose
MINTSOFT_API_KEY	—	Required. Your Mintsoft API key.
MINTSOFT_ENABLE_WRITES	0	Register the write tools.
MINTSOFT_WRITE_CLIENT_ALLOWLIST	(empty)	Comma-separated ClientIds writes may touch. Empty = all writes refused.
MINTSOFT_AUDIT	1	Audit-log every API call.
MINTSOFT_AUDIT_WRITES_ONLY	0	Log only PUT/POST/DELETE.
MINTSOFT_AUDIT_LOG	~/.mintsoft-mcp/mintsoft_api_audit.jsonl	Audit log path.
MINTSOFT_SECRET_PROJECT / MINTSOFT_SECRET_NAME	(unset)	Optional: fetch the key from GCP Secret Manager via gcloud instead.

Smoke test

scripts/smoke_test.py verifies the full 187-endpoint surface: read-only tiers run live; the guarded --write pass runs a create→read→delete cycle only against a client whose name contains "test" (or MINTSOFT_TEST_CLIENT_ID) and skips writes entirely if none exists.

python scripts/smoke_test.py            # read-only
python scripts/smoke_test.py --write    # + guarded write demo

Licence

Apache-2.0.

<!-- MCP registry ownership marker --> mcp-name: io.github.ahamadfalah/mintsoft-mcp