BackCrew Commusoft MCP 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 Commusoft account, so you can ask for things in plain English, such as "find this customer" or "add a new supplier," instead of clicking through the Commusoft 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, including in the UK.

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

• Why use an independent MCP server instead of the platform's own AI?

• What this server actually covers, and why it's small

• 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

• Testing it safely

• For developers

• What's next

• Built by BackCrew

• License

Related MCP server: CiviCRM MCP Server

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

Why use an independent MCP server instead of the platform's own AI?

Software platforms are increasingly shipping their own built-in AI features. Worth knowing why you might still reach for this instead:

• No plan-tier gates. Native AI features are often locked to a platform's most expensive plan. This project just needs API access, which is usually available on lower tiers too.

• Cross-platform, not walled off. A platform's own AI only sees that platform's own data. It has no reason to work fluently with your accounting software, another CRM, or your email, since those are somebody else's product. An MCP-connected assistant can have multiple servers attached at once (this one plus another BackCrew server covering a different part of your business), so it can work across your whole stack in one conversation.

• Your choice of AI, not theirs. You keep using whichever assistant you already trust (Claude, ChatGPT, whatever) instead of learning a new vendor-specific AI interface.

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've done elsewhere in this series when a platform's 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.

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 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 or ChatGPT is told "here's exactly what you're allowed to do, and how to do it."

• Server: a small program that sits between your AI assistant 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 responsibility 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 hand out more trust than you intended. An invalid profile setting falls back to the safest option.

What it can look up (always safe)

7 look-up actions in total.

⚠️ What it can change (off by default)

office-ops level:

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

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 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-commusoft.

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

Step 2: Get your Commusoft credentials

Commusoft's API doesn't have a self-service setup page: everything below has to come from Commusoft support directly. Do this now, before touching the terminal:

1. Contact Commusoft support and ask for API access

2. Ask specifically for your API base URL (Commusoft doesn't publish this anywhere public; you have to ask for it by name)

3. Ask for an Application ID for your integration (they'll ask what kind of app: iPhone/iPad/Android/ThirdParty; say ThirdParty)

4. Confirm the Client ID, username, and password you'll authenticate with

5. Copy all five values into a temporary note somewhere: you'll paste them in during Step 3

Reference: commusoft.docs.apiary.io.

Step 3: Install it

With your folder made and your credentials 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; it 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-commusoft.git .

4. Paste this and press enter; it installs the project's dependencies:

   npm install

5. Paste this and press enter; it builds the project:

   npm run build

6. Paste this and press enter. It 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; it 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 lines for COMMUSOFT_BASE_URL=, COMMUSOFT_APPLICATION_ID=, COMMUSOFT_CLIENT_ID=, COMMUSOFT_USERNAME=, and COMMUSOFT_PASSWORD=. Paste in the matching values you collected in Step 2, right after each =, with no extra spaces or quotes.

10. Leave CS_MCP_MODE=read_only and CS_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.

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

{
  "mcpServers": {
    "commusoft": {
      "command": "node",
      "args": ["PASTE_YOUR_PWD_OUTPUT_HERE/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"
      }
    }
  }
}

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. Also works with other MCP-compatible AI tools (ChatGPT, 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-housecall-pro'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