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

• 70 tools across 12 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 (5 tools)

| Tool | Description | |------|-------------| | list_orders | List work orders with filters (status, customer, location). Valid statuses: Estimate, RepairOrder, Invoice | | get_order | Get full work order details | | create_order | Create a new work order | | update_order | Update work order fields; reports which persisted | | update_service | Update a service's name or note on an order |

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

Customers (6 tools)

| Tool | Description | |------|-------------| | search_customers | Find customers by name, email or phone (see LIMITATIONS: unverified filter) | | search_customers_by_email | Search for a customer by email address | | search_customers_by_phone | Search for a customer by phone number | | get_customer | Get full customer profile | | create_customer | Create a new customer (name and address fields) | | update_customer | Update customer information |

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)

| Tool | Description | |------|-------------| | list_vehicles_for_customer | List all vehicles for a specific customer | | lookup_vehicle_by_vin | Look up a vehicle by VIN number | | lookup_vehicle_by_plate | Look up a vehicle by license plate and region | | list_vehicle_owners | List owners associated with a vehicle | | get_vehicle | Get full vehicle details | | create_vehicle | Add a vehicle (optionally linked to a customer) | | update_vehicle | Update vehicle data |

Inventory & Parts (4 tools)

| 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 by query |

Appointments (4 tools)

| Tool | Description | |------|-------------| | list_appointments | List appointments with date and status filters | | get_appointment | Get full appointment details | | create_appointment | Book a new appointment | | update_appointment | Reschedule or update an appointment |

Payments (3 tools)

| Tool | Description | |------|-------------| | list_payments | List payments for an order | | get_payment | Get payment details | | create_payment | Record a payment (amountCents — integer cents, e.g., $150.50 = 15050) |

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

Technicians & Labor (5 tools)

| Tool | Description | |------|-------------| | list_labor | List labor line items on a service | | assign_technician | Assign a technician to labor lines; verified by read-back | | list_timeclock | Technician clock-in/clock-out events | | list_users | List shop users and technicians | | get_user | Get user/technician profile |

Services & Canned Services (23 tools)

| Tool | Description | |------|-------------| | list_services | List services on work orders | | list_canned_services | List pre-built service templates | | get_canned_service | Get canned service details with line items | | create_canned_service | Create a new canned service template | | update_canned_service | Update a canned service | | delete_canned_service | Delete a canned service template | | list_customer_deferred_services | List deferred (recommended but not yet performed) services |

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

| Fee | Labor | Part | Subcontract | Tire | |-----|-------|------|-------------|------| | add_canned_service_fee | add_canned_service_labor | add_canned_service_part | add_canned_service_subcontract | add_canned_service_tire | | update_canned_service_fee | update_canned_service_labor | update_canned_service_part | update_canned_service_subcontract | update_canned_service_tire | | remove_canned_service_fee | remove_canned_service_labor | remove_canned_service_part | remove_canned_service_subcontract | remove_canned_service_tire |

Webhooks (5 tools)

| Tool | Description | |------|-------------| | list_webhooks | List all registered webhooks | | get_webhook | Get webhook details | | create_webhook | Register a new webhook endpoint with trigger types | | update_webhook | Update a webhook | | delete_webhook | Delete a webhook |

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

Reports — Composite (3 tools)

| Tool | Description | |------|-------------| | report_revenue_summary | Revenue totals by status and paid/unpaid split for a date range | | report_appointment_summary | Appointment counts by confirmation status for a date range | | report_open_estimates | Open unauthorized estimates with age-in-days calculation |

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

Workflow & Locations (2 tools)

| Tool | Description | |------|-------------| | list_workflow_statuses | Get pipeline/workflow stages | | list_locations | List shop locations |

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

| Document | Description | |----------|-------------| | Architecture | System design, dual transport, tool module pattern, client resilience | | Capabilities | All 70 tools with use-case descriptions | | Changelog | Release history | | Credits | Fork authors whose field reports drive this project | | API Provenance | Why v1.0.0 called endpoints that do not exist | | Limitations | Unsupported operations with rationale and workarounds | | Deployment | Railway + Doppler single-tenant deployment guide | | Multi-Tenant Future | Future-work exploration for multi-shop deployment |

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SHOPMONKEY_API_KEY | Yes | — | Shopmonkey API key (Settings > Integration > API Keys) | | SHOPMONKEY_BASE_URL | No | https://api.shopmonkey.cloud/v3 | API base URL | | SHOPMONKEY_LOCATION_ID | No | — | Scope all queries to one location (multi-location shops) | | MCP_AUTH_TOKEN | Cloud: Yes | — | Bearer token for HTTP transport authentication. Required for cloud deployment — omitting it makes the endpoint public. | | PORT | No | 3000 | HTTP transport listening port | | MCP_READ_ONLY | No | — | Set to true to hide and refuse every tool that can change data |

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](https://shop