Serveur MCP Shopmonkey
Commit 26 oct. 2026Permet aux agents IA de gérer les opérations d'un atelier, notamment les ordres de réparation, les clients, les véhicules, l'inventaire, les rendez-vous et les paiements via l'API Shopmonkey.
Aussi connu sous AbbottDevelopments/shopmonkey-mcp-server
- Étoiles
- 3
- Outils
- 54
- Téléchargements, 30 jours
- —
- Dernière version
- —
- Dernier commit
- 26 oct. 2026
- Licence
- MIT
Qu'est-ce que Shopmonkey MCP ?
Permet aux agents IA de gérer les opérations d'un atelier, notamment les ordres de réparation, les clients, les véhicules, l'inventaire, les rendez-vous et les paiements via l'API Shopmonkey. Il expose 54 outils, comme list_orders, get_order, create_order.
Résumé généré à partir du README du projet
À propos du MCP server Shopmonkey
La gestion des opérations d'un atelier automobile via un agent IA est possible grâce à ce serveur, qui se connecte à l'API REST de Shopmonkey. Il propose 70 outils répartis sur 12 groupes de ressources, permettant aux utilisateurs d'interagir avec les ordres de réparation, les profils clients, les données de véhicules, l'inventaire, les rendez-vous et les paiements. Il est conçu pour les développeurs et les gestionnaires d'ateliers qui souhaitent intégrer directement leurs données de gestion dans des clients IA tels que Claude Desktop, Cursor ou Claude Code.
Les utilisateurs peuvent déployer le serveur localement en utilisant le transport stdio ou dans le cloud via streamable HTTP pour une utilisation avec claude.ai. La configuration du serveur nécessite une clé API Shopmonkey fournie sous forme de jeton Bearer. Pour les déploiements dans le cloud, un MCP_AUTH_TOKEN est également requis pour sécuriser le point de terminaison. Le système inclut des fonctionnalités de résilience intégrées, telles que des tentatives automatiques avec backoff exponentiel pour les limites de débit et les erreurs serveur, un délai d'attente de requête de 30 secondes et un contrôle de la concurrence pour limiter les appels API simultanés à cinq.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Outils MCP Shopmonkey 54
Détectés depuis le READMElist_ordersget_ordercreate_orderupdate_orderupdate_servicesearch_customerssearch_customers_by_emailsearch_customers_by_phoneget_customercreate_customerupdate_customerlist_vehicles_for_customer
| list_orders | — | |
| get_order | — | |
| create_order | — | |
| update_order | — | |
| update_service | — | |
| search_customers | — | |
| search_customers_by_email | — | |
| search_customers_by_phone | — | |
| get_customer | — | |
| create_customer | — | |
| update_customer | — | |
| list_vehicles_for_customer | — |
Afficher les 54 outilsAfficher moins d'outils
lookup_vehicle_by_vinlookup_vehicle_by_platelist_vehicle_ownersget_vehiclecreate_vehicleupdate_vehiclelist_inventory_partsget_inventory_partlist_inventory_tiressearch_partslist_appointmentsget_appointmentcreate_appointmentupdate_appointmentlist_paymentsget_paymentcreate_paymentlist_laborassign_technicianlist_timeclocklist_usersget_userlist_serviceslist_canned_servicesget_canned_servicecreate_canned_serviceupdate_canned_servicedelete_canned_servicelist_customer_deferred_servicesadd_canned_service_feeupdate_canned_service_feeremove_canned_service_feelist_webhooksget_webhookcreate_webhookupdate_webhookdelete_webhookreport_revenue_summaryreport_appointment_summaryreport_open_estimateslist_workflow_statuseslist_locations
| lookup_vehicle_by_vin | — | |
| lookup_vehicle_by_plate | — | |
| list_vehicle_owners | — | |
| get_vehicle | — | |
| create_vehicle | — | |
| update_vehicle | — | |
| list_inventory_parts | — | |
| get_inventory_part | — | |
| list_inventory_tires | — | |
| search_parts | — | |
| list_appointments | — | |
| get_appointment | — | |
| create_appointment | — | |
| update_appointment | — | |
| list_payments | — | |
| get_payment | — | |
| create_payment | — | |
| list_labor | — | |
| assign_technician | — | |
| list_timeclock | — | |
| list_users | — | |
| get_user | — | |
| list_services | — | |
| list_canned_services | — | |
| get_canned_service | — | |
| create_canned_service | — | |
| update_canned_service | — | |
| delete_canned_service | — | |
| list_customer_deferred_services | — | |
| add_canned_service_fee | — | |
| update_canned_service_fee | — | |
| remove_canned_service_fee | — | |
| list_webhooks | — | |
| get_webhook | — | |
| create_webhook | — | |
| update_webhook | — | |
| delete_webhook | — | |
| report_revenue_summary | — | |
| report_appointment_summary | — | |
| report_open_estimates | — | |
| list_workflow_statuses | — | |
| list_locations | — |
Configuration
SHOPMONKEY_API_KEY
| Nom | Description | Type |
|---|---|---|
| SHOPMONKEY_API_KEY | — |
Vérifications automatisées
Exécuté le 14 nov. 2026Rapport complet →Pas encore vérifié. Un serveur nécessite un score de 80, aucune faille sérieuse et suffisamment de données pour que nous puissions effectuer les vérifications. Fonctionnement des vérifications · Ce qu'il faut corriger pour gagner des points
- Dépôt source lié et accessibleabbottdevelopments/shopmonkey-mcp-server is public and reachablegithub.com/abbottdevelopments/shopmonkey-mcp-server ↗Réussi
- Le nom du package correspond au dépôt sourceNon vérifié
- Provenance du build (attestation Sigstore)Non vérifié
- Licence open source (OSI)MITspdx.org/licenses/MIT.html ↗Réussi
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-10-26github.com/abbottdevelopments/shopmonkey-mcp-server ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNon vérifié
- Aucun avis critique dans le package ou ses dépendancesNon vérifié
- Aucune instruction cachée destinée au modèle54 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésNon vérifié
- Le point de terminaison distant répond à la poignée de main MCPNon vérifié
README
Voir sur GitHubShopmonkey 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_IDor per-requestlocationId - 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_TOKENto requireAuthorization: Bearer <token>on all MCP requests. Open access when unset (local development). - Health check —
GET /healthandGET /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/emailand/phone_numberto 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
*Centsnaming. 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-Afterheader - 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-readablemessagefield
API Reference
License
Questions sur Shopmonkey MCP
Quels outils Shopmonkey MCP fournit-il ?
Il expose 54 outils, dont list_orders, get_order, create_order, update_order, update_service.
Comment s'authentifier avec le MCP server de Shopmonkey ?
Le serveur utilise l'authentification par clé API Shopmonkey via un jeton Bearer.
Puis-je utiliser ce serveur dans le cloud ?
Oui, le serveur prend en charge le transport streamable HTTP spécifiquement pour le déploiement dans le cloud et la connexion à claude.ai.
Le serveur prend-il en charge les ateliers multi-sites ?
Oui, vous pouvez gérer plusieurs sites en utilisant la variable d'environnement SHOPMONKEY_LOCATION_ID ou en spécifiant un locationId dans les requêtes individuelles.
Existe-t-il un moyen d'empêcher l'IA de modifier mes données ?
Oui, vous pouvez définir la variable d'environnement MCP_READ_ONLY sur true pour masquer et refuser tous les outils capables de modifier des données.