BrinkCommerce Dev MCP Server

Beta Release: This package is in beta. APIs may change. Please report issues on GitHub.

A Model Context Protocol (MCP) server that provides Claude and other AI assistants with both deep knowledge of BrinkCommerce APIs and direct management capabilities. Explore API documentation, create products, manage inventory, update prices, configure stores, and more.

⚠️ Important: Safety Notice for Write Operations

Use with caution: This MCP server can modify your BrinkCommerce configuration including products, prices, inventory, orders, and more. AI agents cannot be fully controlled by the server - safety is your responsibility.

Critical Recommendations

1. NEVER enable auto-accept for tool calls when using AI assistants with this MCP server
2. Review every write operation before approving - the AI will do exactly what you approve
3. Use read-only mode first for exploration (omit API credentials)
4. Test in a staging environment before connecting to production

Why Manual Review is Critical

The MCP protocol has no mechanism to force user confirmation - all safety measures are advisory. The AI will generate correct parameters for any operation it decides to perform. The only real protection is you reviewing each tool call before it executes.

Read-Only Mode

To use this MCP server in read-only mode for API documentation exploration only:

• Simply don't configure the BRINK_CLIENT_ID and BRINK_CLIENT_SECRET environment variables
• All write operations will fail with authentication errors
• Documentation tools (list_apis, search_schemas, etc.) will work normally

What It Does

This MCP server gives AI assistants access to:

• 23 BrinkCommerce APIs - Product, Order, Inventory, Pricing, and Payment integrations
• Direct Management - Create products, manage inventory, update prices, configure stores
• Natural Language Queries - "How do I create a product?" or "Show me the Order schema"
• Smart Search - Find APIs and schemas by field names across the entire platform
• Offline-First - All specs cached locally for instant responses

Requirements

• Node.js 18+ (for npx)

Set Up the Server

Choose your AI development tool and follow the setup instructions:

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "brinkcommerce": {
      "command": "npx",
      "args": ["-y", "brinkcommerce-dev-mcp@beta"]
    }
  }
}

Restart Claude Desktop after saving.

Claude Code (CLI)

claude mcp add brinkcommerce -- npx -y brinkcommerce-dev-mcp@beta

Cursor

1. Open Settings → Tools and Integrations → MCP Servers
2. Click Add new MCP Server
3. Add this configuration:

{
  "mcpServers": {
    "brinkcommerce": {
      "command": "npx",
      "args": ["-y", "brinkcommerce-dev-mcp@beta"]
    }
  }
}

VS Code (Copilot)

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "brinkcommerce": {
        "command": "npx",
        "args": ["-y", "brinkcommerce-dev-mcp@beta"]
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "brinkcommerce": {
      "command": "npx",
      "args": ["-y", "brinkcommerce-dev-mcp@beta"]
    }
  }
}

Windows Troubleshooting

If you have connection issues on Windows, use this alternative configuration:

{
  "mcpServers": {
    "brinkcommerce": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "brinkcommerce-dev-mcp@beta"]
    }
  }
}

Configure API Access (Optional)

The server works out of the box for API documentation queries. To use management tools (create products, update inventory, etc.), add your BrinkCommerce credentials:

Claude Desktop

{
  "mcpServers": {
    "brinkcommerce": {
      "command": "npx",
      "args": ["-y", "brinkcommerce-dev-mcp@beta"],
      "env": {
        "BRINK_CLIENT_ID": "your-client-id",
        "BRINK_CLIENT_SECRET": "your-client-secret",
        "BRINK_CUSTOMER_NAME": "your-customer-name"
      }
    }
  }
}

Claude Code

claude mcp add brinkcommerce \
  -e BRINK_CLIENT_ID=your-client-id \
  -e BRINK_CLIENT_SECRET=your-client-secret \
  -e BRINK_CUSTOMER_NAME=your-customer-name \
  -- npx -y brinkcommerce-dev-mcp@beta

Other Tools

Add the environment variables to your tool's MCP configuration using the env property as shown above.

Start Using

Once configured, try these queries in your AI assistant:

API Documentation:

• "What BrinkCommerce APIs are available?"
• "Show me the Order schema"
• "Find all APIs that handle payments"

Direct Management (requires API credentials):

• "Create a product parent called 'Blue T-Shirt'"
• "Update inventory for variant-123 to 50 units"
• "Set prices for product in Sweden and Norway"
• "Create a B2C store group"

Alternative Installation

From Source

git clone https://github.com/brinkcommerce/brinkcommerce-dev-mcp.git
cd brinkcommerce-dev-mcp
make setup
make claude-config  # Generate configuration

Global Install

npm install -g brinkcommerce-dev-mcp

Available Tools

API Documentation Tools

| Tool | Description | Example | |------|-------------|---------| | get_docs_info | Platform overview and documentation | Start here for introduction | | search_schemas | Find data models by field names | Search for "email", "price", "inventory" | | list_apis | List all available APIs | See all 23 BrinkCommerce APIs | | get_api_info | Get details about a specific API | Learn about ProductManagement API | | list_endpoints | List API endpoints | Find all POST endpoints | | get_endpoint_details | Get endpoint specifications | See how to GET /products/{id} | | list_schemas | List data models for an API | View all Order schemas | | get_schema | Get schema field details | Examine Product model |

Product Management Tools

| Tool | Description | Required Parameters | |------|-------------|-------------------| | get_product_parent | Get a product parent by ID | productParentId | | create_product_parent | Create or update a product parent | productParentId, name, description, displayNames, displayDescriptions | | patch_product_parent | Partially update a product parent (only update specified fields) | productParentId | | delete_product_parent | Delete a product parent | productParentId | | archive_product_parent | Archive a product parent (soft delete) | productParentId | | get_product_variant | Get a product variant by ID | productVariantId | | list_product_variants | List all variants for a product parent | productParentId | | create_product_variant | Create or update a product variant | productVariantId, productParentId, taxGroupId, imageUrl | | patch_product_variant | Partially update a product variant (only update specified fields) | productVariantId | | delete_product_variant | Delete a product variant | productVariantId |

Addon Tools

| Tool | Description | Required Parameters | |------|-------------|-------------------| | get_addon | Get an addon by ID | addonId | | create_or_update_addon | Create or update an addon | addonId, name, description, displayNames, displayDescriptions, taxGroupId, imageUrl | | patch_addon | Partially update an addon (only update specified fields) | addonId | | delete_addon | Delete an addon | addonId | | list_product_parent_addons | List addons for a product parent | productParentId | | add_product_parent_addon | Add an addon to a product parent | productParentId, addonId | | remove_product_parent_addon | Remove an addon from a product parent | productParentId, addonId |

Store Management Tools

| Tool | Description | Required Parameters | |------|-------------|-------------------| | list_store_groups | List all store groups | - | | get_store_group | Get a store group by ID | storeGroupId | | create_or_update_store_group | Create or update a store group | storeGroupId, name, description | | patch_store_group | Partial update of a store group | storeGroupId | | delete_store_group | Delete a store group | storeGroupId | | list_store_markets | List all markets for a store group | storeGroupId | | create_or_update_store_market | Create or update a store market | storeGroupId, countryCode, currencyCode, isTaxIncludedInPrice | | patch_store_market | Partial update of a store market | storeGroupId, countryCode | | delete_store_market | Delete a store market | storeGroupId, countryCode |

Stock Management Tools

| Tool | Description | Required Parameters | |------|-------------|-------------------| | list_inventories | List all inventory locations | - | | get_inventory | Get a specific inventory location | inventoryId | | create_or_update_inventory | Create or update an inventory location | inventoryId, name, description | | delete_inventory | Delete an inventory location | inventoryId | | get_product_variant_stock | Get stock information for a product variant | productVariantId | | update_product_variant_stock_config | Update stock config for a variant (validateStock) | productVariantId, validateStock | | update_product_variant_inventory | Update inventory for a product variant | productVariantId, inventoryId, quantity | | patch_product_variant_inventory | Adjust inventory quantity (add/subtract) | productVariantId, inventoryId, quantityAdjustment | | delete_product_variant_inventory | Delete inventory for a product variant | productVariantId, inventoryId | | get_store_market_inventories | Get store market inventory configuration | storeGroupId, countryCode | | update_store_market_inventories | Update store market inventory priorities | storeGroupId, countryCode, inventoryIds |

Price Management Tools

| Tool | Description | Required Parameters | |------|-------------|-------------------| | get_product_variant_all_prices | Get all prices for a variant across all store groups | productVariantId | | get_product_variant_prices | Get prices for a variant in a specific store group | storeGroupId, productVariantId | | get_product_variant_price | Get single price for a variant in a specific market | storeGroupId, countryCode, productVariantId | | get_addon_price | Get price for an addon in a specific market | storeGroupId, countryCode, addonId | | update_product_variant_prices | Update prices for a product variant across markets | storeGroupId, productVariantId, productVariantPrices | | patch_product_variant_prices | Partial update of product variant prices | storeGroupId, productVariantId, priceUpdates | | delete_product_variant_prices | Price deletion not available (update to zero instead) | N/A |

Order Management Tools

Core Operations: | Tool | Description | Required Parameters | |------|-------------|-------------------| | get_order | Get order by ID | orderId | | get_order_by_reference | Get order by reference | reference | | cancel_order | Cancel an order | orderId | | refund_order | Refund an order | orderId | | import_order | Import external order | orderData | | create_delivery | Create delivery for order | orderId, deliveryData | | create_release | Create release for order | orderId, releaseData |

Order Queries: | Tool | Description | Required Parameters | |------|-------------|-------------------| | get_orders_by_email | Search orders by customer email | email | | get_orders_by_merchant_ref | Search orders by merchant reference | merchantRef1 | | get_order_history | Get order status history | orderId | | get_order_reservation | Get stock reservation info | orderId | | delete_order | Delete order (30+ days old only) | orderId |

Order Collections: | Tool | Description | Required Parameters | |------|-------------|-------------------| | list_order_deliveries | List all deliveries for an order | orderId | | list_order_cancellations | List all cancellations for an order | orderId | | list_order_refunds | List all refunds for an order | orderId | | list_order_releases | List all releases for an order | orderId | | list_order_compensations | List all compensations for an order | orderId | | list_order_modifications | List all modifications for an order | orderId |

Compensations (partial refunds without returns): | Tool | Description | Required Parameters | |------|-------------|-------------------| | create_compensation | Create compensation | orderId, request | | get_compensation | Get compensation details | compensationId | | update_compensation | Update before starting | compensationId, request | | delete_compensation | Delete before starting | compensationId | | start_compensation | Start compensation processing | compensationId | | restart_compensation | Restart failed compensation | compensationId |

Order Lines Modifications: | Tool | Description | Required Parameters | |------|-------------|-------------------| | create_order_lines_modification | Create order lines mod | orderId, request | | get_order_lines_modification | Get modification details | modificationId | | update_order_lines_modification | Update before starting | modificationId, request | | delete_order_lines_modification | Delete before starting | modificationId | | start_order_lines_modification | Start modification | modificationId | | restart_order_lines_modification | Restart failed modification | modificationId |

Shipping Fees Modifications: | Tool | Description | Required Parameters | |------|-------------|-------------------| | create_shipping_fees_modification | Create shipping fees mod | orderId, request | | get_shipping_fees_modification | Get modification details | modificationId | | update_shipping_fees_modification | Update before starting | modificationId, request | | delete_shipping_fees_modification | Delete before starting | modificationId | | start_shipping_fees_modification | Start modification | modificationId | | restart_shipping_fees_modification | Restart failed modification | modificationId |

Addresses Modifications: | Tool | Description | Required Parameters | |------|-------------|-------------------| | create_addresses_modification | Create addresses mod | orderId, request | | get_addresses_modification | Get modification details | modificationId | | update_addresses_modification | Update before starting | modificationId, request | | delete_addresses_modification | Delete before starting | modificationId | | start_addresses_modification | Start modification | modificationId |

Custom States (control order operations): | Tool | Description | Required Parameters | |------|-------------|-------------------| | list_custom_states | List all custom states | - | | get_custom_state | Get custom state details | stateId | | create_custom_state | Create custom state | stateId, name | | delete_custom_state | Delete custom state | stateId | | add_order_custom_state | Add state to order | orderId, stateId | | remove_order_custom_state | Remove state from order | orderId, stateId |

Custom Reason Codes: | Tool | Description | Required Parameters | |------|-------------|-------------------| | list_custom_reason_codes | List all reason codes | - | | get_custom_reason_code | Get reason code details | code | | create_custom_reason_code | Create reason code | code, name | | delete_custom_reason_code | Delete reason code | code |

Order Comments: | Tool | Description | Required Parameters | |------|-------------|-------------------| | create_order_comment | Add comment to order | orderId, text | | update_order_comment | Update existing comment | orderId, commentId, text | | delete_order_comment | Delete comment | orderId, commentId |

Discount Management Tools

| Tool | Description | Required Parameters | |------|-------------|-------------------| | run_discounts | Run discount calculations | discountRunData | | get_bundle_group | Get bundle group by ID | bundleGroupId | | create_or_update_bundle_group | Create or update bundle group | bundleGroupId, bundleGroupData | | delete_bundle_group | Delete bundle group | bundleGroupId | | create_discount_code | Create a discount code | discountCodeData |

Tax Management Tools

| Tool | Description | Required Parameters | |------|-------------|-------------------| | get_tax_group | Get tax group by ID | taxGroupId | | create_or_update_tax_group | Create or update tax group | taxGroupId, taxGroupData | | delete_tax_group | Delete tax group | taxGroupId | | get_tax_markets | Get tax markets for a tax group | taxGroupId | | create_or_update_tax_market | Create or update tax market | taxGroupId, countryCode, taxMarketData | | delete_tax_market | Delete tax market | taxGroupId, countryCode |

Testing

# Quick test
make test

# Interactive testing with MCP Inspector
make inspect
# Open http://localhost:6274

Development

# Development mode with hot reload
make dev

# Run all checks
make check

# View all commands
make help

Configuration

Environment Variables

| Variable | Description | Default | Required | |----------|-------------|---------|----------| | BRINK_CLIENT_ID | OAuth2 client ID for BrinkCommerce API | - | For management tools | | BRINK_CLIENT_SECRET | OAuth2 client secret for BrinkCommerce API | - | For management tools | | BRINK_CUSTOMER_NAME | Your BrinkCommerce customer name | - | For management tools | | BRINK_REGION | BrinkCommerce region (eu-west-1, us-east-1) | eu-west-1 | Optional | | BRINK_API_KEY | API key for additional authentication | - | Optional | | BRINKCOMMERCE_CACHE_DIR | Cache directory location | Platform-specific | Optional | | SPECS_FORCE_REFRESH | Force refresh all specs on startup | false | Optional | | LOG_LEVEL | Logging verbosity (debug/info/warn/error) | info | Optional |

Troubleshooting

Server not connecting?

1. Verify Node.js 18+: node --version
2. Test npx directly: npx -y brinkcommerce-dev-mcp@beta
3. Restart your AI tool completely
4. Check the tool's developer console for errors

Windows issues?

Use the cmd wrapper configuration shown in Windows Troubleshooting

Cache issues?

SPECS_FORCE_REFRESH=true npx brinkcommerce-dev-mcp@beta

Need debug output?

LOG_LEVEL=debug npx brinkcommerce-dev-mcp@beta

Documentation

• Testing Guide - Comprehensive testing documentation
• Architecture - Technical implementation details
• Claude Setup - AI-assisted development guide
• BrinkCommerce Docs - Platform documentation

License

MIT - see LICENSE file

Support

• Issues: GitHub Issues
• MCP Protocol: modelcontextprotocol.io