Shopmonkey MCP Server

A Model Context Protocol (MCP) server that wraps the Shopmonkey REST API (v3), enabling AI agents and LLMs to interact with shop management data — work orders, customers, vehicles, inventory, appointments, payments, labor, services, and more.

Features

• 33 tools across 9 resource groups covering the full Shopmonkey API
• Bearer token authentication via API key
• Automatic retry with exponential backoff on rate limits (HTTP 429) and server errors (500/502/503/504)
• 30-second request timeout prevents hung connections
• Request concurrency control (max 5 simultaneous API calls)
• Multi-location support via SHOPMONKEY_LOCATION_ID default or per-request locationId
• Descriptive error messages surfacing Shopmonkey error codes
• Works with Claude Desktop, Cursor, Claude Code, and any MCP-compatible client

Tool Reference

Work Orders

Customers

Vehicles

Inventory & Parts

Appointments

Payments

Technicians & Labor

Services

Workflow & Locations

Setup

Prerequisites

• Node.js 18+
• A Shopmonkey API key (create at: Shopmonkey Settings > Integration > API Keys)

Installation

git clone https://github.com/AbbottDevelopments/shopmonkey-mcp-server.git
cd shopmonkey-mcp-server
npm install
npm run build

Environment Variables

Copy .env.example to .env and add your API key:

cp .env.example .env

Then edit .env:

# Required — your Shopmonkey API key
SHOPMONKEY_API_KEY=your_long_lived_api_key_here

# Optional — defaults to https://api.shopmonkey.cloud/v3
SHOPMONKEY_BASE_URL=https://api.shopmonkey.cloud/v3

# Optional — set this for multi-location shops to auto-filter all queries to one location
SHOPMONKEY_LOCATION_ID=

The server loads .env automatically via dotenv. You can also pass environment variables through your MCP client config (see below) or your shell.

MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "shopmonkey": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/shopmonkey-mcp-server",
      "env": {
        "SHOPMONKEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "shopmonkey": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/shopmonkey-mcp-server",
      "env": {
        "SHOPMONKEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Code

claude mcp add shopmonkey -e SHOPMONKEY_API_KEY=your_api_key_here -- node /path/to/shopmonkey-mcp-server/dist/index.js

Development

# Build
npm run build

# Watch mode
npm run dev

# Start server
npm start

# Run tests
npm test

Error Handling

The server handles common API scenarios:

• Missing API key: Returns a descriptive error with setup instructions
• Rate limiting (429): Automatically retries with exponential backoff (up to 3 attempts)
• Server errors (500, 502, 503, 504): Automatically retries with backoff
• Request timeout: Aborts after 30 seconds with a clear error message
• Network failures: Retries with backoff, returns readable error messages
• API errors: Surfaces Shopmonkey error codes (e.g., API-xxxxx, ORM-xxxxx) for debugging

API Reference

• Shopmonkey API Docs
• API Base URL
• MCP Protocol

License

MIT