BackCrew ServiceM8 Server

Think of this like a brand-new employee on their first day, not a business partner. A new hire only does the exact tasks you've shown them, nothing more, until you decide they're ready for more responsibility.

It lets you connect an AI assistant like Claude or ChatGPT to your ServiceM8 account, so you can ask for things in plain English (think "find this client," "what's on the schedule today," or "add a note to this job") instead of clicking through the ServiceM8 app yourself. On day one, it only knows how to look things up. You decide if and when to train it up to doing more.

Built by BackCrew, part of a series of free tools like this for the software pest control companies use every day.

Not a developer? That's fine. Everything up through "Testing it safely" is written for you, no coding background needed.

Already know ServiceM8 has its own official AI connector? Jump to Why use an independent MCP server instead of ServiceM8's official one?

---

Contents

• What this actually does
• Why use an independent MCP server instead of ServiceM8's official one?
• Also from BackCrew
• Some words you'll see, explained
• How this keeps you safe by default
• What it can look up (always safe)
• ⚠️ What it can change (off by default)
• How to set it up
• Connecting it to Claude
• Things you can try asking
• Testing it safely
• For developers
• What's next
• Built by BackCrew
• License

What this actually does

Let's be upfront about what this is, because it's easy to oversell: this is not an all-knowing office assistant that understands your business and handles things for you. It's a specific, listed set of actions (like "look up a client," "create a job," or "add a note") that an AI assistant is allowed to trigger when you ask for them in plain English. The AI doesn't have judgment about your business; it matches what you ask for to the closest action on its list and does exactly that, nothing more.

That's still genuinely useful. Instead of this:

Open ServiceM8 → search clients → click into the record → find the right job → scroll to find the note you're after...

You can just say:

"Find the client named Dana Ruiz and show me her open jobs."

And the assistant does the clicking for you, using the same actions you'd take yourself, just faster and in plain English.

Why use an independent MCP server instead of ServiceM8's official one?

Fair question, and we looked into this carefully before building. ServiceM8 does ship an official, hosted MCP integration (https://api.servicem8.com/mcp) that connects directly through ChatGPT's or Claude's built-in connector UI via OAuth: no code, no self-hosting. Based on ServiceM8's own support documentation, it currently covers: searching/listing clients, jobs, job filters, staff, queues, allocation windows, forms, categories, badges, tax rates, and job templates; viewing job details, diary entries, and notes; creating jobs from templates; adding notes; checking staff availability; scheduling jobs; sending jobs to queues; changing job status; and sending job-linked email/SMS.

That's a genuinely good, zero-setup option if it covers what you need. And if your ServiceM8 account already gives you (or your workspace admin) permission to add a custom connector, there's no reason not to use it alongside this one. Worth noting up front: ServiceM8's official connector is itself an MCP server, so it already sidesteps one of the usual reasons to go independent: you're not locked into a proprietary in-app chat, you can point it at Claude or ChatGPT either way.

Where this project differs:

• Broader coverage. ServiceM8's official list doesn't appear to include client/company record management (creating or editing a client), job payments, materials/line items, suppliers, company contacts, attachments, or a general cross-object search. This project covers all of those, because they're part of ServiceM8's public REST API even though the official MCP doesn't expose them yet.
• No workspace-admin approval needed. ServiceM8's official connector requires "permission to add a custom app or connector," which in Claude Team/Enterprise accounts means an Owner has to add it for the org first. This project just needs an API key you generate yourself from your own account settings, so a solo operator can use it without asking anyone.
• Cross-platform, not walled off. ServiceM8's official connector only talks to ServiceM8. This project can run alongside another BackCrew server covering a different part of your business, attached to the same AI assistant, so it can work across your whole stack in one conversation.
• Self-hosted and readable. This runs on your own machine, not ServiceM8's infrastructure. You (or anyone) can read exactly what each tool does in src/tools/: nothing is a black box.
• The same tiered-safety model as the rest of this series. Read-only by default, with an explicit readonly-owner / office-ops / admin profile system you control: see How this keeps you safe by default. ServiceM8's official connector is governed by its own OAuth scopes and workspace admin settings instead.
• Consistent with our other builds. If you're also using other BackCrew servers, this one follows the identical pattern: same mental model, same setup steps, same safety controls.

In short: use ServiceM8's official connector for zero-setup job search/scheduling/communication. Use this one if you want broader coverage, don't have connector-approval permissions, or want it working alongside your other business systems in one conversation.

Also from BackCrew

This is one of several MCP connectors BackCrew builds, same idea, different software. We've also got QuickBooks for the accounting side, plus CRM connectors like HubSpot and GoHighLevel for lead and marketing data. Full list and what's live right now: see ROADMAP.md.

Beyond this repo: once a business gets comfortable with an AI assistant reading its data, there's often more it wants to do with it, like catching missed calls faster, processing invoices and paperwork automatically, following up on quotes without someone having to remember, reactivating customers who've gone quiet, or pulling reports without digging through the software. That's a separate, scoped conversation, not part of this free, open-source repo. Same contact as in Built by BackCrew below if it's something you want to explore.

Some words you'll see, explained

• API: short for "Application Programming Interface." A locked door into ServiceM8's data that only software (not a person clicking a mouse) can open. This project is a key that opens that door, so an AI can read and update your data directly instead of needing a screen to click through.
• MCP: short for "Model Context Protocol." The standard way an AI assistant like Claude or ChatGPT is told "here's exactly what you're allowed to do, and how to do it." This project speaks that standard, which is why it plugs into Claude, ChatGPT, and similar tools with no custom setup.
• Server: a small program that sits between your AI assistant and ServiceM8, translating requests back and forth. You start it once and leave it running; you never interact with it directly.
• Repo (short for "repository"): the folder of code for this whole project. "Clone the repo" just means "download a copy of this project."
• API key: a long, private password-like code that proves a request is really coming from you. You generate it from your own ServiceM8 account (steps below) and never share it.
• Terminal: a plain-text window where you type commands instead of clicking buttons. Setup involves a few terminal commands, listed step-by-step below.
• Tool: one specific action the AI is allowed to take, like "look up a client" or "create a job." Each one is listed and named individually; there's no hidden catch-all action.

How this keeps you safe by default

The new-hire idea from the top is the real architecture, not just a nice way of putting it:

• Out of the box, this server can only look things up. It ships in read-only mode: nothing it does can create, change, or delete anything in your ServiceM8 account, because those actions aren't even switched on.
• When you're ready for more, you choose a responsibility level, not an all-or-nothing switch. Turning on write access (SM8_MCP_MODE=read_write, see setup) still requires picking a profile that caps what's allowed:
  • readonly-owner: same as the default. Look-ups only.
  • office-ops: everyday work, add/update a client, create and update jobs, schedule activities, add notes and tasks, attach files. No deletes, no staff-record changes, no recording payments. Those stay off even in this mode.
  • admin: everything, including deletes, staff records (which include login email and location data), and recording job payments.
• A typo can't accidentally hand out more trust than you intended. If the profile setting is ever misspelled or invalid, the server falls back to the safest option (read-only) rather than the most permissive one.

What it can look up (always safe)

These actions only read data; nothing here can change a record or cost you anything to run. This is what's available in the default setup, with no extra steps:

What it covers	Examples of what it can look up
Clients	Search and view client profiles and their contacts
Jobs	View job details, scheduled activities, contacts, line items, payment history
Staff	View technicians and office staff
Catalog	View materials, job categories, dispatch queues, suppliers, tax rates
Notes & tasks	View notes and to-do tasks
Attachments	View files (photos, quotes, invoices) linked to jobs and clients
Inbox	View incoming lead/message inbox
Job templates	View pre-built job templates
Search	Free-text search across everything

36 look-up actions in total.

⚠️ What it can change (off by default)

Everything below this line can create, edit, or delete something real in your ServiceM8 account. None of it is available until you deliberately turn it on (see How this keeps you safe by default). This section exists so you know exactly what you'd be turning on, not because it's active right now.

office-ops level (everyday actions):

What it covers	Examples of what it can do
Clients	Add or update a client and their contacts
Jobs	Create/update a job, schedule activities, add job contacts and line items
Catalog	Add or update materials, categories, queues, suppliers, tax rates
Notes & tasks	Add notes, create/update tasks
Attachments	Attach a file to a job or client
Inbox	Convert a message to a job, attach it to a job, mark read/archived/snoozed, add a note
Job templates	Create a job from a template

admin level only (hard to reverse, financially sensitive, or HR-facing, kept separate from everyday office work on purpose):

• Deleting any record (clients, jobs, materials, tasks, etc.)
• Creating or updating staff records (kept separate from front-desk work since they include login email and GPS location fields)
• Creating or updating job payments (financially consequential)

How to set it up

No context-switching here: do these three steps in order, and you won't need to jump back and forth.

You'll need a computer with Node.js installed (free software this project runs on) before you start.

Step 1: Make a folder for this on your computer

Open Finder (Mac) or File Explorer (Windows), go to your Desktop or Documents, and create a new folder. Give it a name you'll recognize later, like backcrew-mcp-servicem8.

That's it for now. Just know where this folder is. Everything else gets put inside it.

Step 2: Get your ServiceM8 API key

Unlike ServiceM8's official connector, this doesn't need a Developer Center account or app registration: just a key from your own account. Do this now, before touching the terminal:

1. Log into your ServiceM8 account
2. Go to Settings → API Keys
3. Click to generate a key, then copy it into a temporary note somewhere; you'll paste it in during Step 3

Reference: developer.servicem8.com/docs/authentication.

Step 3: Install it

With your folder made and your API key in hand, this is one continuous run: don't skip ahead or double back.

1. Open a terminal. On a Mac, press Cmd+Space, type "Terminal," and hit enter. On Windows, click the Start menu, type "PowerShell," and hit enter. Use PowerShell rather than Command Prompt: a couple of the commands below, like pwd, only work in PowerShell.
2. Type cd (with a space after it), then drag your Step 1 folder from Finder/File Explorer straight into the terminal window; it'll paste the folder's path in automatically. Press enter.
3. Paste this exact command and press enter, which downloads the project directly into the folder you made (the trailing . matters, it means "put it here, not in a new folder"):

   git clone https://github.com/jayson-svg/backcrew-mcp-servicem8.git .
   

4. Paste this and press enter, which installs the project's dependencies:

   npm install
   

5. Paste this and press enter, which builds the project:

   npm run build
   

6. Paste this and press enter, which prints the full folder path. Don't close this terminal window yet; you'll need this exact text in the next section.

   pwd
   

7. Paste this and press enter, which creates your settings file from a template:

   cp .env.example .env
   

8. Open that new .env file in a text editor. On a Mac, paste open -e .env into the terminal and press enter. On Windows, paste notepad .env and press enter.
9. Find the line that says SERVICEM8_API_KEY=. Paste in the key you copied in Step 2, right after the =, with no extra spaces or quotes.
10. Leave SM8_MCP_MODE=read_only and SM8_MCP_PROFILE=readonly-owner exactly as they are for now. That's the safe default. Save the file and close the editor.

Connecting it to Claude

This step comes last on purpose: it needs the exact folder location from Step 3, and now you have it.

Claude Desktop / Claude Code

Open Claude's settings file (for Claude Desktop, this is claude_desktop_config.json) and add:

{
  "mcpServers": {
    "servicem8": {
      "command": "node",
      "args": ["PASTE_YOUR_PWD_OUTPUT_HERE/dist/index.js"],
      "env": {
        "SERVICEM8_API_KEY": "your_key_here",
        "SM8_MCP_MODE": "read_only",
        "SM8_MCP_PROFILE": "readonly-owner"
      }
    }
  }
}

Replace PASTE_YOUR_PWD_OUTPUT_HERE with the exact text the pwd command printed back in Step 3 (keep the /dist/index.js part after it). If you're on Windows, swap any backslashes in that path for forward slashes (for example C:/Users/yourname/Desktop/... instead of C:\Users\yourname\Desktop\...), since the config file needs regular slashes.

Restart Claude. You should see ServiceM8 show up as something Claude can use, with only the look-up actions available, by default.

This also works with other MCP-compatible AI tools (ChatGPT, Cursor, Windsurf, and others); the setup step is basically the same.

Things you can try asking

With the default (read-only) setup:

• "Find the client named Dana Ruiz"
• "What jobs are scheduled for today?"
• "Show me the notes on this job"
• "What's in the inbox that hasn't been triaged yet?"

If you later turn on office-ops:

• "Create a new client for this address and add a job for a termite inspection"
• "Add a note to this job saying the gate code changed"
• "Convert that inbox message into a job"
• "Schedule this job for tomorrow morning and assign it to Mike"

Testing it safely

If and when you decide to turn on write access, a few habits go a long way:

1. Start in read-only mode and stay there for a while. Get a feel for how the AI interprets your requests before you ever let it change anything.
2. When you do turn on office-ops, test on a clearly fake client first. Create a test client named something obvious like "ZZZ Test Client: Do Not Use" and try your first few write actions on that record, not a real one.
3. Never go straight to admin mode. Deletes, staff records, and payments are hard or impossible to undo. office-ops covers real day-to-day work without exposing any of that.
4. Never share your API key: in chat, in a screenshot, in a support ticket, anywhere. Treat it like a password, because it functions like one.
5. If something looks wrong, switch back to SM8_MCP_MODE=read_only immediately. That alone guarantees nothing further can be changed, regardless of what profile is set.

For developers

Everything below this point assumes a coding background.

Tool reference

Run the server and call tools/list from any MCP client to see exact input/output schemas: every tool's description includes both the ServiceM8 API operation it maps to and its access tier (e.g. Maps to POST /job.json. [tier: office-ops]). Each domain lives in its own file under src/tools/.

Why this repo uses a CRUD factory instead of hand-written tools per resource

Most other repos in this series hand-write each tool individually, because those APIs genuinely have bespoke, non-uniform endpoints per resource. ServiceM8's REST API is different: nearly every resource (Client, Job, Staff, Material, Task, and so on) exposes the exact same list / get / create / update / delete shape, just with different field names. Hand-writing that ~15 times over would be pure repetition, so this repo has one small factory, registerCrudResource() in src/crud.ts, that generates the five tools for a resource from one config object (resource path, field list, access tiers). Each generated tool is still a fully separate, individually named, individually gated MCP tool: the factory only removes boilerplate, it doesn't merge or hide any capability. Resources with a non-uniform shape (Inbox messages, Search, Job Templates, Notes, Attachments) are still hand-written in their own files, same as the other repos.

The tier/profile system

Every tool declares a tier: "readonly-owner" | "office-ops" | "admin". At startup, src/toolkit.ts reads SM8_MCP_MODE and SM8_MCP_PROFILE once, computes the maximum exposed tier, and any tool above that tier is never registered with the MCP server: it's genuinely absent from tools/list, not just hidden. SM8_MCP_MODE=read_only always wins over SM8_MCP_PROFILE; only read_write lets the profile setting take effect. An unrecognized profile value falls back to readonly-owner. Same pattern as the rest of this series: see ROADMAP.md.

Project layout

src/
  index.ts          Server entrypoint, registers every tool group and starts stdio transport
  client.ts          Minimal fetch-based ServiceM8 API client (auth header, cursor pagination, error handling)
  toolkit.ts          Tier/profile-aware helper that wires a Zod input schema + handler into an MCP tool
  crud.ts             Factory that generates list/get/create/update/delete tools for uniform-CRUD resources
  tools/
    clients.ts         (Client/Company + Company Contacts)
    jobs.ts             (Jobs, Job Activities, Job Contacts, Job Materials, Job Payments)
    staff.ts
    catalog.ts          (Materials, Job Categories, Job Queues, Suppliers, Tax Rates)
    notesAndTasks.ts
    attachments.ts
    inbox.ts
    templates.ts        (Job Templates)
    search.ts

Notes on the ServiceM8 API

• Base URL: https://api.servicem8.com/api_1.0/{resource}.json
• Auth header: X-Api-Key: <api_key>
• Filtering: OData-style $filter query param (eq, ne, gt, lt; up to 10 conditions joined with and); lt/gt are supported but le/ge are not
• Pagination: cursor-based. Start with cursor=-1, use the x-next-cursor response header for the next page (up to 1000 records/page); its absence means you've reached the end
• Full reference: developer.servicem8.com

This server was built by reading ServiceM8's public API documentation directly, including the full OpenAPI schema their docs site serves (confirmed via the API reference pages themselves), not by guessing or reverse-engineering another project. If you spot a field that's drifted from what ServiceM8 actually returns, please open an issue or PR.

This repo intentionally stops at honest API access. It does not include business-logic features (like a prioritized collections queue, technician capacity analysis, or automated escalation rules). Those live in BackCrew's managed offering, built on top of this open layer, not in this public repo. See ROADMAP.md.

Scope

ServiceM8's API covers roughly 40 resources; this repo covers the ~24 most central to day-to-day field service operations (88 tools). Not yet covered: Allocation Windows, Asset Types/Asset Type Fields/Assets, Availabilities, Badges, Bundles/Job Material Bundles, Document Templates, Email Templates, Feedback, Forms/Form Fields/Form Responses, Job Allocations, Job Checklists, Knowledge Articles, Locations, Security Roles, SMS Templates, Staff Messages, and the read-only Email/SMS/Vendor endpoints. Contributions welcome.

What's next

See ROADMAP.md for the rest of the planned series and the pattern this repo follows.

Built by BackCrew

This project is free and open for anyone to use, copy, or build on; that's the whole point.

It's also a sample of the kind of work BackCrew does: we build tools, automations, and AI setups like this one for pest control and field service businesses, including the business-logic layer (collections, capacity planning, escalation rules) that intentionally isn't part of this open repo. If you like what this does but don't want to set it up and maintain it yourself, or you want something built specifically for how your business runs, that's exactly the kind of project we take on.

Want this set up for you? Reach out: [email protected]

No pressure either way: everything above works on its own, for free.

License

MIT