BackCrew Commusoft 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 Commusoft account, so you can ask for things in plain English — "find this customer," "add a new supplier" — instead of clicking through the Commusoft 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, including in the UK. First entry: Housecall Pro.

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

Important scope note up front: Commusoft's public API turned out to be much smaller and older than the other platforms in this series. Read What this server actually covers — and why it's small before you get your hopes up for full job/invoicing coverage — it's not there yet, because Commusoft's own public docs don't cover it.

---

Contents

• What this actually does
• What this server actually covers — and why it's small
• 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
• 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 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.

What this server actually covers — and why it's small

Be upfront about this: Commusoft's public API reference is old, small, and only partially documented by Commusoft themselves. It covers 7 resources — Customers, Suppliers, Contacts, Diary Events, Users, Titles, Locations — and even within those, several endpoints are stub-documented in Commusoft's own reference (their example request bodies are literally empty placeholders for Contacts, Diary Events, and Users). There is no public documentation for Jobs, Quotes, Invoices, or Payments, even though Commusoft the product clearly has all of that (we found third-party integration reports referencing job-related endpoints that simply aren't in the public reference).

This server covers exactly what's genuinely documented:

• Customers, Suppliers, Titles: full create/read/update/delete, with real field names taken directly from Commusoft's published API Blueprint
• Locations: create/read/update (no delete endpoint exists in the public docs)
• Contacts: read plus a best-effort create (Commusoft's own docs don't specify this endpoint's fields — verify against a real account before relying on it)
• Diary Events, Users: read-only, and even that is thin — Commusoft's docs don't specify these resources' fields at all

One more real gap: Commusoft never publishes their API's base URL anywhere public. You'll need to get that — along with an Application ID — directly from Commusoft support before this can call a live account. See setup.

We're shipping this at its true size rather than padding it with guessed endpoints, same as we did for GorillaDesk when its public API turned out to be small too. If Commusoft expands or clarifies their public docs, this server will grow to match — see ROADMAP.md.

Some words you'll see, explained

• API — short for "Application Programming Interface." A locked door into Commusoft's data that only software (not a person clicking a mouse) can open. This project is a key that opens that door.
• 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."
• Server — a small program that sits between Claude and Commusoft, translating requests back and forth. You start it once and leave it running.
• Repo (short for "repository") — the folder of code for this whole project.
• Token — a temporary code Commusoft issues after you provide your username/password/Application ID, used to authenticate further requests. This server fetches and manages it automatically.
• Terminal — a plain-text window where you type commands instead of clicking buttons.
• Tool — one specific action the AI is allowed to take, like "look up a customer." Each one is listed and named individually.

How this keeps you safe by default

• 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 Commusoft account.
• When you're ready for more, you choose a badge level, not an all-or-nothing switch. Turning on write access (CS_MCP_MODE=read_write) still requires picking a profile:
  • readonly-owner — same as the default. Look-ups only.
  • office-ops — add/edit customers, suppliers, contacts, titles, locations. No deletes.
  • admin — everything, including deletes (which Commusoft cannot undo).
• A typo can't accidentally open more doors than intended. An invalid profile setting falls back to the safest option.

What it can look up (always safe)

What it covers	Examples
Customers	Look up a customer's record
Suppliers	Look up a supplier's record
Titles	Look up a salutation setting (Mr, Mrs, Dr, etc.)
Locations	Look up a system-settings location
Contacts	Look up a contact linked to a customer or supplier
Diary events, Users	Look up by ID (thin — see scope note above)

7 look-up actions in total.

⚠️ What it can change (off by default)

office-ops level:

What it covers	Examples
Customers, Suppliers, Titles, Locations	Add or update a record
Contacts	Best-effort create (see scope note — fields aren't fully documented by Commusoft)

admin level only:

• Deleting a customer, supplier, or title. Commusoft soft-deletes — the record is flagged and cannot be un-deleted, which is exactly the kind of hard-to-reverse action this tier exists to gate.

How to set it up

You'll need:

• A computer with Node.js installed
• Commusoft API credentials from Commusoft support directly — see below

Step 1: Download the project

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

Step 2: Get your Commusoft API credentials

Commusoft's API doesn't have a self-service setup page. You'll need to contact Commusoft directly and ask for:

1. Your API base URL (Commusoft doesn't publish this anywhere public — you have to ask)
2. An Application ID for your integration (they'll ask what kind of app: iPhone/iPad/Android/ThirdParty)
3. Confirm the username/password/Client ID you'll authenticate with

Reference: commusoft.docs.apiary.io.

Step 3: Save your credentials and choose your safety level

cp .env.example .env

Edit .env:

COMMUSOFT_BASE_URL=https://whatever-commusoft-gives-you
COMMUSOFT_APPLICATION_ID=your_application_id
COMMUSOFT_CLIENT_ID=your_client_id
COMMUSOFT_USERNAME=your_username
COMMUSOFT_PASSWORD=your_password

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

Save the file. Keep it private.

Connecting it to Claude

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

{
  "mcpServers": {
    "commusoft": {
      "command": "node",
      "args": ["/absolute/path/to/backcrew-mcp-commusoft/dist/index.js"],
      "env": {
        "COMMUSOFT_BASE_URL": "https://whatever-commusoft-gives-you",
        "COMMUSOFT_APPLICATION_ID": "your_application_id",
        "COMMUSOFT_CLIENT_ID": "your_client_id",
        "COMMUSOFT_USERNAME": "your_username",
        "COMMUSOFT_PASSWORD": "your_password",
        "CS_MCP_MODE": "read_only",
        "CS_MCP_PROFILE": "readonly-owner"
      }
    }
  }
}

Restart Claude. Also works with other MCP-compatible AI tools (Cursor, Windsurf, etc.).

Testing it safely

1. Start in read-only mode and stay there for a while.
2. When you turn on office-ops, test on a clearly fake customer first — something obvious like "ZZZ Test Customer — Do Not Use."
3. Never go straight to admin mode. Commusoft's deletes cannot be undone.
4. Never share your credentials — treat them like a password.
5. If something looks wrong, switch back to CS_MCP_MODE=read_only immediately.

For developers

Everything below this point assumes a coding background.

Tool reference

Run the server and call tools/list to see exact schemas — every tool's description includes the Commusoft API path it maps to and its access tier.

Project layout

src/
  index.ts          Server entrypoint
  client.ts          Fetches and caches an auth token, then calls the Commusoft API
  toolkit.ts          Tier/profile-aware helper that wires a Zod input schema + handler into an MCP tool
  tools/
    customers.ts
    suppliers.ts
    titles.ts
    locations.ts
    misc.ts            (Contacts, Diary Events, Users — thin/best-effort)

The tier/profile system

Same pattern as the rest of this series: every tool declares a tier, CS_MCP_MODE/CS_MCP_PROFILE gate what's actually registered at startup, read_only always wins over the profile setting, and an invalid profile falls back to the safest tier. See backcrew-mcp's README for the original writeup.

Notes on the Commusoft API

• Auth: POST {base_url}/api/v1/getToken with clientId, username, password, applicationId in the body, returning a plain-text token. Subsequent requests pass that token as a token query parameter. This client fetches the token lazily on first use and caches it for the process lifetime.
• The base URL is not published anywhere in Commusoft's public documentation. It must come from Commusoft support. This is a real, confirmed gap — we searched extensively before concluding it's genuinely not public.
• Record creation requires the caller to generate and supply a UUID — Commusoft doesn't generate one for you.
• Deletes are soft-deletes (a Deleted flag + audit record) and are permanent from the API's perspective.
• Full reference: commusoft.docs.apiary.io — note this Apiary-hosted site has been observed returning intermittent 502 errors; if it's down, retry rather than assuming it's gone permanently.
• Evidence suggests Commusoft has a more complete, modern API (used for official integrations like their Zapier connector, which references job-related endpoints) that isn't reflected in this public reference. If you're a Commusoft partner with access to fuller documentation, contributions extending this repo are very welcome.

This repo intentionally stops at honest API access. It does not include business-logic features — those live in BackCrew's managed offering, not in this public repo. See ROADMAP.md.

What's next

See ROADMAP.md for the rest of the planned series.

Built by BackCrew

This project is free and open for anyone to use, copy, or build on.

It's also a sample of the kind of work BackCrew does: we build tools, automations, and AI setups for pest control and field service businesses. If you'd rather not track down Commusoft's undocumented base URL yourself, or you want the job/invoicing coverage this public API doesn't expose, that's exactly the kind of project we take on.

Want this done for you? Reach out: jayson@backcrew.co

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

License

MIT