MCP Server Setup

The ShipRules AI MCP (Model Context Protocol) server lets AI assistants like Claude Desktop and Cursor manage your shipping rules directly. You can ask Claude to “add a $5 surcharge for Alaska” and it will use the MCP tools to do it.

Installation

npm install @shiprules/mcp

Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "shiprules": {
      "command": "npx",
      "args": ["@shiprules/mcp"],
      "env": {
        "SHIPRULES_API_KEY": "sr_live_your_key_here"
      }
    }
  }
}

Add to your project’s .mcp.json:

{
  "mcpServers": {
    "shiprules": {
      "command": "npx",
      "args": ["@shiprules/mcp"],
      "env": {
        "SHIPRULES_API_KEY": "sr_live_your_key_here"
      }
    }
  }
}

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "shiprules": {
      "command": "npx",
      "args": ["@shiprules/mcp"],
      "env": {
        "SHIPRULES_API_KEY": "sr_live_your_key_here"
      }
    }
  }
}

Replace sr_live_your_key_here with your actual API key. See Authentication for how to create one.

Available tools

The MCP server exposes 24 tools organized into 6 categories:

Read (8)

Tool	Description
`list_zones`	List all shipping zones with countries and subzones
`list_product_groups`	List product groups and variant assignments
`list_methods`	List shipping methods for a zone (optionally by product group)
`list_rules`	List rules for a shipping method
`list_blended_rates`	List all blended rates with preferences
`get_settings`	Get shop settings, plan, and usage
`get_version_history`	Get paginated version history
`simulate_rate`	Simulate a rate calculation with destination + cart items

Write — Rules (3)

Tool	Description
`create_rule`	Create a rule on a shipping method
`update_rule`	Update a rule’s action, conditions, or position
`delete_rule`	Delete a rule

Write — Methods (3)

Tool	Description
`create_method`	Create a shipping method (flat, weight-tiered, etc.)
`update_method`	Update a method’s config, threshold, or enabled status
`delete_method`	Delete a method and its rules

Write — Product Groups (2)

Tool	Description
`create_product_group`	Create a product group
`assign_products`	Assign variants to a group

Bulk (2)

Tool	Description
`export_config`	Export full configuration as JSON snapshot
`import_config`	Import a configuration snapshot (with optional preview)

Staging / Shadow Mode (4)

Tool	Description
`enter_staging`	Enter staging mode for shadow testing
`promote_staged`	Promote staged changes to live
`discard_staged`	Discard staged changes
`get_shadow_results`	Get shadow comparison results

Version Control (2)

Tool	Description
`rollback`	Roll back to a previous version
`diff_versions`	Compare two configuration versions

Example conversation

Here’s what a conversation with Claude Desktop looks like when the ShipRules AI MCP server is connected:

You: “Show me all my shipping methods for the US zone”

Claude: Uses list_zones to find the US zone ID, then list_methods filtered by that zone. Shows you a formatted list of methods with their rates.

You: “Add a $5 surcharge on Standard Shipping for Alaska and Hawaii”

Claude: Uses list_methods to find Standard Shipping’s ID, then create_rule with action adjust_add, adjustmentValue 500, and a destination_state condition for AK,HI. Confirms the rule was created.

You: “Test that — simulate an order to Alaska with a $50 cart”

Claude: Uses simulate_rate with a test cart going to AK. Shows you the rate results including the $5 surcharge and the rule trace proving it fired.

You: “Looks good. Now show me what changed in the last 3 versions”

Claude: Uses get_version_history with limit 3, then diff_versions between the oldest and newest. Shows a summary of what was added, modified, or removed.

Troubleshooting

“Tool not found” error in Claude Desktop Make sure you’ve restarted Claude Desktop after adding the MCP config. The server needs to be running.

“Unauthorized” error from tools Check that your SHIPRULES_API_KEY environment variable is set correctly and the key hasn’t been revoked.

“Plan limit exceeded” error MCP server access requires the Enterprise plan. Check your plan at Settings > Billing.