This MCP server lets AI agents interact with Shopmonkey shop-management data via 70 API-wrapping tools over stdio or Streamable HTTP.
Work orders: list, retrieve, create, and update orders.
Customers: search, look up by email/phone, get, create, and update customer profiles.
Vehicles: list customer vehicles, VIN/plate lookup, owner lookup, get, create, and update vehicles.
Inventory: list parts/tires, get part details, and search the parts catalog.
Appointments: list, get, create, and update/reschedule appointments.
Payments: list, get, and record payments using integer cents.
Technicians & labor: list labor lines, assign technicians, view timeclock events, list users, and get user profiles.
Services: list order services, add services including from canned templates, and manage canned services.
Canned-service line items: add/update/remove fee, labor, part, subcontract, and tire items.
Webhooks: list, get, create, update, and delete webhooks with trigger types.
Reports: revenue summary, appointment summary, and open-estimate aging.
Locations & workflow: list locations and workflow statuses.
Labels: list, get, and assign labels to entities.
Operations: API-key auth, multi-location scoping, retries, timeouts, health checks, and optional read-only mode.
Supports deployment of the MCP server to Railway cloud platform for HTTP transport, enabling cloud-based access to Shopmonkey shop management tools through Claude.ai and other MCP-compatible clients.
Supports deployment of the MCP server to Render cloud platform for HTTP transport, enabling cloud-based access to Shopmonkey shop management tools through Claude.ai and other MCP-compatible clients.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Shopmonkey MCP Server find all open work orders for customer John Doe"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
Related MCP server: Thinkific MCP Server
git clone https://github.com/AbbottDevelopments/shopmonkey-mcp-server.git
cd shopmonkey-mcp-server
npm install
npm run buildCopy .env.example to .env and add your Shopmonkey API key:
cp .env.example .env
# Edit .env — set SHOPMONKEY_API_KEY to your keyStart the server:
# stdio (local use with Claude Desktop, Cursor, Claude Code)
npm start
# HTTP (cloud deployment, Claude.ai)
npm run start:httpThe server ships two entry points sharing a single tool registry — use whichever matches your deployment target.
node dist/index.js
# or: npm startYour MCP client spawns this process directly. Used by Claude Desktop, Cursor, and Claude Code. See MCP Client Configuration below.
PORT=3000 node dist/http.js
# or: npm run start:httpThe 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 | Description |
| List work orders with filters (status, customer, location). Valid statuses: |
| Get full work order details |
| Create a new work order |
| Update work order fields; reports which persisted |
| 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.
Tool | Description |
| Find customers by name, email or phone (see LIMITATIONS: unverified filter) |
| Search for a customer by email address |
| Search for a customer by phone number |
| Get full customer profile |
| Create a new customer (name and address fields) |
| Update customer information |
Email and phone are sub-resources in Shopmonkey. After creating a customer, use
POST /v3/customer/:id/emailand/phone_numberto attach contact info. See docs/LIMITATIONS.md.
Tool | Description |
| List all vehicles for a specific customer |
| Look up a vehicle by VIN number |
| Look up a vehicle by license plate and region |
| List owners associated with a vehicle |
| Get full vehicle details |
| Add a vehicle (optionally linked to a customer) |
| Update vehicle data |
Tool | Description |
| List parts inventory |
| Get single part details |
| List tire inventory |
| Search parts catalog by query |
Tool | Description |
| List appointments with date and status filters |
| Get full appointment details |
| Book a new appointment |
| Reschedule or update an appointment |
Tool | Description |
| List payments for an order |
| Get payment details |
| Record a payment ( |
All money values use integer cents with
*Centsnaming. Never send decimal dollar amounts.
Tool | Description |
| List labor line items on a service |
| Assign a technician to labor lines; verified by read-back |
| Technician clock-in/clock-out events |
| List shop users and technicians |
| Get user/technician profile |
Tool | Description |
| List services on work orders |
| List pre-built service templates |
| Get canned service details with line items |
| Create a new canned service template |
| Update a canned service |
| Delete a canned service template |
| 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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Tool | Description |
| List all registered webhooks |
| Get webhook details |
| Register a new webhook endpoint with trigger types |
| Update a webhook |
| Delete a webhook |
Supported triggers: Appointment, Customer, Inspection, Inventory, Message, Order, Payment, PurchaseOrder, User, Vehicle, Vendor
Tool | Description |
| Revenue totals by status and paid/unpaid split for a date range |
| Appointment counts by confirmation status for a date range |
| 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.
Tool | Description |
| Get pipeline/workflow stages |
| List shop locations |
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"
}
}
}
}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 mcp add shopmonkey -e SHOPMONKEY_API_KEY=your_api_key_here -- node /path/to/shopmonkey-mcp-server/dist/index.jsDeploy 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.
Document | Description |
System design, dual transport, tool module pattern, client resilience | |
All 70 tools with use-case descriptions | |
Release history | |
Fork authors whose field reports drive this project | |
Why v1.0.0 called endpoints that do not exist | |
Unsupported operations with rationale and workarounds | |
Railway + Doppler single-tenant deployment guide | |
Future-work exploration for multi-shop deployment |
Variable | Required | Default | Description |
| Yes | — | Shopmonkey API key (Settings > Integration > API Keys) |
| No |
| API base URL |
| No | — | Scope all queries to one location (multi-location shops) |
| Cloud: Yes | — | Bearer token for HTTP transport authentication. Required for cloud deployment — omitting it makes the endpoint public. |
| No |
| HTTP transport listening port |
| No | — | Set to |
The server automatically loads .env via dotenv if present. You can also pass variables through your shell or MCP client config.
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.
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
Add a fee line item to an existing canned service template.
Inputs: cannedServiceId (required), name, notes, quantity, +4 more.
Add a labor line item to an existing canned service template.
Inputs: cannedServiceId (required), name, note, hours, +3 more.
Add a part line item to an existing canned service template.
Inputs: cannedServiceId (required), name, note, taxable, +4 more.
Add a subcontract line item to an existing canned service template.
Inputs: cannedServiceId (required), name, notes, quantity, +4 more.
Add a tire line item to an existing canned service template.
Inputs: cannedServiceId (required), name, notes, quantity, +4 more.
Add a service to a work order. Pass fromCannedServiceId to copy an existing canned service template (its labor, parts, fees) onto the order in one call, or pass name/note/pricing to create a custom one-off service instead.
Inputs: orderId (required), name, note, pricing, +1 more.
Assign an existing label (found via list_labels) to an entity such as an Order or Customer.
Inputs: entity (required), labelId (required), entityId (required).
Assign a technician to one or more labor line items on a work order. Use list_services (orderId) to find the serviceId, list_labor (orderId + serviceId) to find labor IDs, and list_users to find the technician's user ID.
Inputs: orderId (required), laborIds (required), technicianId (required).
Book a new appointment in Shopmonkey.
Inputs: notes, title, endDate, orderId, +4 more.
Create a new canned service template in Shopmonkey. Canned services are reusable service bundles that can be added to work orders.
Inputs: name, express, lumpSum, pricing, +5 more.
Create a new customer in Shopmonkey.
Inputs: zip, city, state, address, +2 more.
Create a new work order in Shopmonkey.
Inputs: name, status, vehicleId, customerId, +1 more.
Record a new payment in Shopmonkey.
Inputs: orderId (required), amountCents (required), notes, method.
Add a new vehicle to Shopmonkey, optionally linked to a customer.
Inputs: vin, make, year, color, +4 more.
Create a new webhook in Shopmonkey. Use this to register Make.com or other endpoint URLs that receive Shopmonkey event notifications.
Inputs: url (required), name (required), triggers (required), secret, +2 more.
Delete a canned service template by ID.
Inputs: id (required).
Delete a webhook by ID.
Inputs: id (required).
Get detailed information about a single appointment by its ID.
Inputs: id (required).
Get detailed information about a single canned service template by its ID.
Inputs: id (required).
Get detailed information about a single customer by their ID.
Inputs: id (required).
Get detailed information about a single inventory part by its ID.
Inputs: id (required).
Get a single label by its ID.
Inputs: id (required).
Get detailed information about a single work order by its ID.
Inputs: id (required).
Get detailed information about a single payment by its ID.
Inputs: id (required).
Get detailed information about a single shop user or technician by their ID.
Inputs: id (required).
Get detailed information about a single vehicle by its ID.
Inputs: id (required).
Get details of a single webhook by ID.
Inputs: id (required).
List appointments from Shopmonkey. Supports filtering and pagination. Date-filtered queries are routed through the /appointment/search endpoint, which applies the range server-side.
Inputs: skip, limit, endDate, startDate, +2 more.
List pre-built canned service templates from Shopmonkey. These are reusable service templates that can be added to work orders.
Inputs: skip, limit, locationId.
List deferred services (recommended-but-not-yet-performed work) for a customer. Useful for revenue-opportunity surfacing in chat.
Inputs: customerId (required), skip, limit.
List parts from Shopmonkey inventory. Supports pagination.
Inputs: skip, limit, locationId.
List tires from Shopmonkey inventory. Supports pagination.
Inputs: skip, limit, locationId.
List labels defined in Shopmonkey (custom tags such as "Warranty" or "Fleet"). Filter by exact name to find a label ID before assigning it.
Inputs: name, skip, limit, entity.
List the labor line items on a service. Shopmonkey nests labor under order > service, so both orderId and serviceId are required — call list_services with an orderId first to get the serviceId.
Inputs: orderId (required), serviceId (required).
List all shop locations in Shopmonkey. Useful for multi-location shops to identify location IDs for filtering other resources.
Inputs: skip, limit.
List work orders from Shopmonkey. Filter by status, customer ID, date range, or location.
Inputs: skip, limit, status, customerId, +1 more.
List payments from Shopmonkey. Supports filtering and pagination.
Inputs: skip, limit, orderId, locationId.
List the services on a work order. Shopmonkey nests services under their order — there is no flat service list — so orderId is required.
Inputs: orderId (required), skip, limit.
List technician time clock events. Track clock-in/clock-out for shop staff.
Inputs: skip, limit, userId, endDate, +2 more.
List shop users and technicians from Shopmonkey.
Inputs: skip, limit, locationId.
List all customers who own or are associated with a specific vehicle.
Inputs: vehicleId (required).
List all vehicles associated with a specific customer.
Inputs: customerId (required), skip, limit.
List all registered webhooks in Shopmonkey.
Inputs: skip, limit.
List workflow/pipeline status stages from Shopmonkey. Shows the progression stages work orders move through.
Inputs: locationId.
Look up a vehicle in Shopmonkey by its license plate and region.
Inputs: plate (required), region (required).
Look up a vehicle in Shopmonkey by its VIN (Vehicle Identification Number).
Inputs: vin (required).
Remove a fee line item from a canned service template.
Inputs: itemId (required), cannedServiceId (required).
Remove a labor line item from a canned service template.
Inputs: itemId (required), cannedServiceId (required).
Remove a part line item from a canned service template.
Inputs: itemId (required), cannedServiceId (required).
Remove a subcontract line item from a canned service template.
Inputs: itemId (required), cannedServiceId (required).
Remove a tire line item from a canned service template.
Inputs: itemId (required), cannedServiceId (required).
Generate an appointment summary for a date range. Counts appointments by confirmation status (Confirmed/Declined/NoResponse). Uses the /appointment/search endpoint, which filters by date server-side.
Inputs: endDate (required), startDate (required), locationId.
List all open (unauthorized) estimates, showing their age in days. Useful for follow-up on stale estimates. Pages the full estimate list each call; check the returned truncated flag if the shop is very large.
Inputs: locationId.
Generate a revenue summary for orders INVOICED within a date range (filtered on invoicedDate, not order creation date). Aggregates by status and splits paid vs. unpaid revenue. Pages the full order list each call for a consistent total — check the returned truncated flag if the shop is very large.
Inputs: endDate (required), startDate (required), locationId.
Search customers in Shopmonkey by query string. Supports full-body search with pagination.
Inputs: skip, limit, query, locationId.
Search for a customer in Shopmonkey by email address.
Inputs: email (required).
Search for a customer in Shopmonkey by phone number.
Inputs: phoneNumber (required).
Search the parts catalog in Shopmonkey. Use for finding parts by name, number, or description.
Inputs: query (required), skip, limit.
Update or reschedule an existing appointment.
Inputs: id (required), notes, title, endDate, +4 more.
Update an existing canned service template by ID.
Inputs: id (required), name, express, lumpSum, +5 more.
Update a fee line item on a canned service template.
Inputs: itemId (required), cannedServiceId (required), name, notes, +5 more.
Update a labor line item on a canned service template.
Inputs: itemId (required), cannedServiceId (required), name, note, +4 more.
Update a part line item on a canned service template.
Inputs: itemId (required), cannedServiceId (required), name, note, +6 more.
Update a subcontract line item on a canned service template.
Inputs: itemId (required), cannedServiceId (required), name, notes, +5 more.
Update a tire line item on a canned service template.
Inputs: itemId (required), cannedServiceId (required), name, notes, +5 more.
Update an existing customer's information.
Inputs: id (required), zip, city, state, +3 more.
Update fields on an existing work order.
Inputs: id (required), name, status, vehicleId, +1 more.
Update an existing vehicle's information.
Inputs: id (required), vin, make, year, +5 more.
Update an existing webhook by ID.
Inputs: id (required), url, name, secret, +3 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 69 tools
Most tools have distinct verb-noun names and clear descriptions, but some pairs like list_inventory_parts vs. search_parts and list_appointments vs. report_appointment_summary could cause minor confusion. Overall, an agent can usually tell them apart.
Names consistently follow snake_case verb_noun structures, but there is slight inconsistency among read operations: get, list, search, lookup, and report are all used for similar retrieval purposes. Still, the naming is mostly predictable and readable.
With 69 tools, this is far beyond the typical well-scoped range and falls into the extreme category. The large number of nested canned-service line-item operations contributes to the bulk, making the surface area heavy and difficult to navigate.
The toolset covers the core Shopmonkey entities—customers, vehicles, orders, appointments, payments, inventory, webhooks, reports, labels, and canned services—quite thoroughly. A few main-entity delete operations are absent, but this may reflect domain constraints rather than a gap.
Discover, inspect and run 63,000+ agent tools from one balance. Pay per call, no subscriptions.
Run a service business from your AI agent: CRM, leads, scheduling, invoicing, jobs and more.
Verified, pay-per-use API tools for AI agents through one authenticated connection.
Aircraft intelligence for AI agents: valuations with uncertainty bands, FAA registry lookups, cost of ownership, comparable aircraft, fleet search, airworthiness directives and STCs, market metrics and forecasts, verified value reports, pre-buy diligence checklists, logbook search and a watchlist. 38 tools; free tier with OAuth or a Windsock API key.
