BackCrew ServiceM8 MCP Server

Think of this project as an employee badge, not a master key.

It lets you connect an AI assistant like Claude to your ServiceM8 account, so you can ask for things in plain English — "find this client," "what's on the schedule today," "add a note to this job" — instead of clicking through the ServiceM8 app yourself. But like a real employee badge, it only opens the specific doors you hand it a key for. Out of the box, every door is locked to "look, don't touch." You choose if and when to hand it keys to anything more.

Built by BackCrew — part of a series of free tools like this for the software pest control companies use every day. First entry: Housecall Pro.

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 ServiceM8 already has an official MCP — why build another one?

---

Contents

• What this actually does
• ServiceM8 already has an official MCP — why build another one?
• 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

To be precise about what this is, because it's easy to overstate: 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 — "look up a client," "create a job," "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.

ServiceM8 already has an official MCP — why build another 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.

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 — a solo operator can use it without asking anyone.
• 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 our Housecall Pro, GorillaDesk, or FieldRoutes 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 the same self-hosted setup as the rest of this series.

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 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 (and similar tools) with no custom setup.
• Server — a small program that sits between Claude 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 badge metaphor 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 badge 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 open more doors than 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

You'll need:

• A computer with Node.js installed (free software this project runs on)
• A ServiceM8 account (only needed once you're ready to connect to your real account — not needed to download and look at the project)

Step 1: Download the project

Open a terminal and type:

git clone https://github.com/jayson-svg/backcrew-mcp-servicem8.git
cd backcrew-mcp-servicem8
npm install
npm run build

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.

1. Log into your ServiceM8 account
2. Go to Settings → API Keys
3. Generate a key and copy it

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

Step 3: Save your key and choose your safety level

cp .env.example .env

Open the new .env file in any text editor:

SERVICEM8_API_KEY=your_key_here

# Leave these two exactly as they are until you've read
# "Testing it safely" below and are ready for more than look-ups.
SM8_MCP_MODE=read_only
SM8_MCP_PROFILE=readonly-owner

Save the file. Keep it private — anyone with this key can access your ServiceM8 data.

Connecting it to Claude

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": ["/absolute/path/to/backcrew-mcp-servicem8/dist/index.js"],
      "env": {
        "SERVICEM8_API_KEY": "your_key_here",
        "SM8_MCP_MODE": "read_only",
        "SM8_MCP_PROFILE": "readonly-owner"
      }
    }
  }
}

Replace /absolute/path/to/backcrew-mcp-servicem8 with wherever you downloaded the project.

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 (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

Every other repo in this series (Housecall Pro, FieldRoutes) hand-writes 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 backcrew-mcp (Housecall Pro).

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: jayson@backcrew.co

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

License

MIT