MCP 服务器

Shopmonkey MCP Server

Enables AI agents to interact with the Shopmonkey REST API to manage shop management data including work orders, customers, vehicles, and inventory. It provides 33 tools across 9 resource groups with built-in support for rate limiting, concurrency control, and multi-location management.

README

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

Tool	Description
`list_orders`	List work orders with filters (status, customer, location)
`get_order`	Get single work order details
`create_order`	Create new work order
`update_order`	Update work order fields
`delete_order`	Permanently delete a work order (requires `confirm: true`)

Customers

Tool	Description
`list_customers`	List customers, searchable by name/email/phone
`get_customer`	Get single customer profile
`create_customer`	Add new customer
`update_customer`	Update customer info

Vehicles

Tool	Description
`list_vehicles`	List vehicles, filter by customer
`get_vehicle`	Get single vehicle details
`create_vehicle`	Add vehicle (optionally linked to customer)
`update_vehicle`	Update vehicle data

Inventory & Parts

Tool	Description
`list_inventory_parts`	List parts inventory
`get_inventory_part`	Get single part details
`list_inventory_tires`	List tire inventory
`search_parts`	Search parts catalog (query required)

Appointments

Tool	Description
`list_appointments`	List appointments
`get_appointment`	Get single appointment
`create_appointment`	Book appointment
`update_appointment`	Reschedule/update appointment

Payments

Tool	Description
`list_payments`	List payments
`get_payment`	Get payment details
`create_payment`	Record a payment (orderId and amount required)

Technicians & Labor

Tool	Description
`list_labor`	List labor line items
`list_timeclock`	Technician clock-in/clock-out events
`list_users`	List shop users/technicians
`get_user`	Get single user/tech profile

Services

Tool	Description
`list_services`	List services on orders
`list_canned_services`	List pre-built service templates
`get_canned_service`	Get single canned service details

Workflow & Locations

Tool	Description
`list_workflow_statuses`	Get pipeline/workflow stages
`list_locations`	List shop 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