SLAM Commerce

MCP server for SLAM Gadget — expose your Shopify SQLite database to AI tools.

---

Requirements

• Node.js 20+
• A SLAM Gadget .db file (schema version 3, downloaded from the Gadget dashboard)

---

Installation

Step 1 — Install globally (required for fast startup)

npm install -g @slam-commerce/mcp@2

Why global? Native modules like better-sqlite3 must compile once on your machine. Using npx causes a 10–30 second cold start on every session while npm reinstalls and recompiles. Global install runs that cost once.

On Windows, if the install fails with a node-gyp error, first run:

npm install -g node-gyp@latest
npm install -g @slam-commerce/mcp@2

Step 2 — Point to your database

The server resolves the database path using the first of these that matches:

Priority	Mechanism	Best for
1	--db <path> CLI argument	Project-level .mcp.json with relative paths
2	SLAM_DB_PATH environment variable	Shared/global client configs
3	Auto-discover ./slam/data/*.db	Drop-in zero-config if your project follows the standard layout

Step 3 — Configure your MCP client

Claude Code — project .mcp.json (recommended, portable)

Place a .mcp.json in your project root. The --db path resolves relative to that directory:

{
  "mcpServers": {
    "slam": {
      "command": "slam-mcp",
      "args": ["--db", "./slam/data/your-store.db"]
    }
  }
}

Move or rename the project folder and it still works. If your project follows the standard SLAM Gadget layout (./slam/data/*.db), you can omit --db entirely and let auto-discovery find the file.

Claude Desktop — add to config:

{
  "mcpServers": {
    "slam": {
      "command": "slam-mcp",
      "args": ["--db", "/absolute/path/to/store.db"]
    }
  }
}

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "slam": {
      "command": "slam-mcp",
      "args": ["--db", "/absolute/path/to/store.db"]
    }
  }
}

Claude Code / Cursor (env var alternative) — run once:

claude mcp add slam --scope user \
  -e "SLAM_DB_PATH=/absolute/path/to/store.db" \
  -- slam-mcp

---

Tools (60 total)

Meta (5 tools)

Tool	Description
slam_health	Server introspection: version, schema_version, freshness, row counts
slam_meta_status	Sync status and row counts per entity table
slam_meta_store	Store metadata (domain, currency, timezone, plan)
slam_meta_schema	Full schema reference with relationships and SQL patterns (call this first before slam_run_query)
slam_metafields_query	Query metafields by owner type and namespace

Products (5 tools)

Tool	Description
slam_products_list	List products with optional filters (status, vendor, product_type, tag)
slam_products_get	Get a single product by ID with variants, collections, metafields
slam_products_search	Full-text search products by title or description
slam_products_count	Count products matching filters
slam_product_images	List product images from the product_media table

Variants (4 tools)

Tool	Description
slam_variants_list	List variants with optional product filter
slam_variants_get	Get a single variant by ID
slam_variants_search	Search variants by SKU, title, or barcode
slam_variant_options	Product options and values from the product_options table

Inventory (6 tools)

Tool	Description
slam_inventory_levels	Inventory levels per variant per location (includes location_name)
slam_inventory_summary	Stock summary across all variants
slam_inventory_alerts	Variants at or below a stock threshold
slam_inventory_oversold	Variants with negative available stock
slam_inventory_by_location	Inventory totals per location with location name
slam_dead_stock	Zero-sales variants with available stock

Collections (4 tools)

Tool	Description
slam_collections_list	List collections with product count
slam_collections_get	Get a collection with its products
slam_collections_for_product	Collections that contain a specific product
slam_products_for_collection	Products within a specific collection

Orders (10 tools)

Tool	Description
slam_orders_list	List orders with optional status/date filters
slam_orders_get	Get a single order with line items and discount codes
slam_orders_search	Search orders by name, email, or note
slam_order_line_items_list	Line items for a specific order
slam_discounts_summary	Summary of discount codes used across orders
slam_discounts_active	Active discount campaigns from the discounts table
slam_fulfillment_tracking	Fulfillment status from the fulfillments table
slam_refunds_summary	Refunds and refund line items
slam_returns_summary	Returns by status and period
slam_draft_orders_list	Draft orders pipeline

Customers (6 tools)

Tool	Description
slam_customers_list	List customers with optional tag filter
slam_customers_get	Get a single customer by ID
slam_customers_by_tag	Tag frequency analysis from the customer_tags table
slam_customers_search	Search customers by email or name
slam_customers_top	Top customers by spend or order count
slam_customer_addresses	Customer address records

Prices (2 tools)

Tool	Description
slam_prices_current	Current prices with compare_at for sale detection
slam_price_analysis	Price distribution and discount analysis

Conditions (6 tools)

Tool	Description
slam_conditions_content	Content/tag conditions for product filtering
slam_conditions_pricing	Price-based conditions
slam_conditions_identifiers	ID/SKU/barcode lookups
slam_conditions_inventory	Inventory-based conditions
slam_conditions_orders	Order history conditions
slam_conditions_customers	Customer conditions

Reporting (5 tools)

Tool	Description
slam_sales_summary	Revenue, order count, AOV summary
slam_sales_by_period	Sales broken down by day/week/month
slam_products_top	Best-selling products by revenue or units
slam_products_bought_together	Frequently co-purchased products
slam_vendors_summary	Vendor performance summary

Store-level (5 tools)

Tool	Description
slam_locations_list	All fulfilment locations with stock summary
slam_b2b_companies_list	B2B company directory with contact count
slam_content_pages	Pages and articles for content auditing
slam_gift_cards_summary	Outstanding gift card balance by currency
slam_selling_plans_list	Subscription/selling plan groups

Snapshot (1 tool)

Tool	Description
slam_store_snapshot	One-call store health overview: sales totals, inventory counts, data condition issue counts, and sync freshness

Ad-hoc (1 tool)

Tool	Description
slam_run_query	Execute any read-only SELECT query against the database (call slam_meta_schema first to understand the schema)

---

Response envelope

Every tool response includes a _meta object:

{
  "_meta": {
    "domain": "products",
    "output_type": "list",
    "last_sync_at": "2024-01-15T08:30:00.000Z",
    "minutes_since_sync": 45,
    "freshness_tier": "stale",
    "returned": 25,
    "offset": 0,
    "has_more": true
  }
}

Freshness tiers

Tier	Condition	Meaning
fresh	< 15 min	Data is current
stale	15–59 min	Minor lag
very_stale	1–24 hours	Re-sync recommended
outdated	≥ 24 hours	Data is old — re-sync now

---

Schema version

This package targets Gadget schema version 3. On startup the server reads _slam_meta.schema_version and writes a warning to stderr if the version does not match. Re-download your .db file from the Gadget dashboard if you see this warning.

---

Known gaps vs V3

The following tools from @slam-commerce/[email protected] were removed because the Gadget database does not have change-tracking tables:

Removed tool	Reason
slam_inventory_history	Requires inventory_snapshots table — not present in Gadget
slam_prices_history	Requires price_snapshots table — not present in Gadget
slam_changes_recent	Requires change_log table — not present in Gadget
slam_changes_for_entity	Requires change_log table — not present in Gadget

---

Security

All database connections open with PRAGMA query_only = 1. The slam_run_query tool additionally validates that the statement is a SELECT and checks the referenced tables against a known-good allowlist before execution.