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, canned services, webhooks, and more.

Features

• 64 tools across 11 resource groups covering the Shopmonkey API

• Dual transport — stdio for local/desktop use, Streamable HTTP for cloud deployment

• Shopmonkey API key authentication (Bearer token to Shopmonkey REST API)

• Automatic retry with exponential backoff on rate limits (429) and server errors (5xx)

• Request concurrency control (max 5 simultaneous API calls)

• 30-second request timeout per call

• Multi-location support via SHOPMONKEY_LOCATION_ID or per-request locationId

• Descriptive error messages surfacing Shopmonkey error codes and messages

• HTTP transport includes bearer auth, health check endpoint, and graceful shutdown

• Works with Claude Desktop, Cursor, Claude Code, Claude.ai, and any MCP-compatible client

Quick Start

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

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

cp .env.example .env
# Edit .env — set SHOPMONKEY_API_KEY to your key

Start the server:

# stdio (local use with Claude Desktop, Cursor, Claude Code)
npm start

# HTTP (cloud deployment, Claude.ai)
npm run start:http

Transports

The server ships two entry points sharing a single tool registry — use whichever matches your deployment target.

stdio (local use)

node dist/index.js
# or: npm start

Your MCP client spawns this process directly. Used by Claude Desktop, Cursor, and Claude Code. See MCP Client Configuration below.

Streamable HTTP (cloud deployment)

PORT=3000 node dist/http.js
# or: npm run start:http

The HTTP server listens on PORT (default 3000) and handles MCP requests at /. Required for cloud deployment (Railway, Render) and for connecting to Claude.ai.

HTTP features:

• Authentication — Set MCP_AUTH_TOKEN to require Authorization: Bearer <token> on all MCP requests. Open access when unset (local development).

• Health check — GET /health and GET / return {"status":"ok"} for load balancer probes.

• Graceful shutdown — Clean exit on SIGTERM/SIGINT with a 5-second timeout.

For cloud deployment instructions, see docs/DEPLOYMENT.md.

Tool Reference

Work Orders (4 tools)

Order deletion is not supported by the Shopmonkey API. See docs/LIMITATIONS.md for details.

Customers (6 tools)

Email and phone are sub-resources in Shopmonkey. After creating a customer, use POST /v3/customer/:id/email and /phone_number to attach contact info. See docs/LIMITATIONS.md.

Vehicles (7 tools)

Inventory & Parts (4 tools)

Appointments (4 tools)

Payments (3 tools)

All money values use integer cents with *Cents naming. Never send decimal dollar amounts.

Technicians & Labor (4 tools)

Services & Canned Services (22 tools)

Canned service line items — 5 types (fee, labor, part, subcontract, tire) with add/update/remove operations:

Webhooks (5 tools)

Supported triggers: Appointment, Customer, Inspection, Inventory, Message, Order, Payment, PurchaseOrder, User, Vehicle, Vendor

Reports — Composite (3 tools)

Reports are composited from list endpoints (max 100 records per report). Use tighter date ranges for larger shops.

Workflow & Locations (2 tools)

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

Claude.ai (HTTP transport)

Deploy dist/http.js to Railway or Render with SHOPMONKEY_API_KEY and MCP_AUTH_TOKEN set as environment variables. See docs/DEPLOYMENT.md for the full guide.

Documentation

Environment Variables

The server automatically loads .env via dotenv if present. You can also pass variables through your shell or MCP client config.

Development

npm run build        # Compile TypeScript
npm run dev          # Watch mode (tsc --watch)
npm start            # Start stdio server
npm run start:http   # Start HTTP server
npm test             # Run test suite (requires build first)

The test suite includes 186 tests across 9 test files covering mock API behavior, MCP protocol compliance, error paths, and transport validation.

Error Handling

The server handles common API scenarios:

• Missing API key — Descriptive error with setup instructions

• Rate limiting (429) — Automatic retry with exponential backoff (up to 3 attempts), respects Retry-After header

• Server errors (500, 502, 503, 504) — Automatic retry with backoff

• Request timeout — 30-second abort with clear error message

• Network failures — Retry with backoff, readable error messages

• API errors — Surfaces Shopmonkey error codes (API-xxxxx, ORM-xxxxx) and human-readable message field

API Reference

• Shopmonkey API Documentation

• Shopmonkey API Base URL

• Model Context Protocol

License

MIT