BackCrew FieldRoutes 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 FieldRoutes (formerly PestRoutes) account, so you can ask for things in plain English — "find this customer," "what's on the route Tuesday," "is this invoice paid" — instead of clicking through the FieldRoutes website 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.

---

Contents

• What this actually does
• A quick note on FieldRoutes' terminology
• 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 customer," "schedule an appointment," "create an invoice" — 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 FieldRoutes → search customers → click into the record → find the right tab → scroll to find this week's appointments...

You can just say:

"Find the customer named Dana Ruiz and show me any appointments scheduled for her this week."

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

A quick note on FieldRoutes' terminology

FieldRoutes uses a few names that don't match what you might expect from other software:

• A "ticket" is an invoice — the bill for work done.
• A "subscription" is a recurring service plan for a customer — the ongoing quarterly/monthly treatment agreement, not a one-off job.
• An "appointment" is a single scheduled visit, which may or may not be tied to a subscription.

The tool names in this project follow FieldRoutes' own terms so they line up with what you'll see in the FieldRoutes app itself.

Some words you'll see, explained

• API — short for "Application Programming Interface." A locked door into FieldRoutes' 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 FieldRoutes, 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."
• Authentication key / token — two long, private password-like codes that prove a request is really coming from you. FieldRoutes issues these to your account directly (steps below) — you never share them.
• 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 customer" or "create an invoice." 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, delete, or charge anything in your FieldRoutes 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 (FR_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 front-desk and dispatch work: book an appointment, update a customer, create an invoice, build a route. No deletes, no employee-record changes, no payment/card handling — those stay off even in this mode.
  • admin — everything, including deletes, employee record management, and anything touching payments or stored card/ACH details.
• 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
Customers	Search and view customer profiles
Appointments	View scheduled visits and their status
Invoices (tickets)	View invoices and their line items
Recurring service plans (subscriptions)	View a customer's ongoing service agreement
Employees	View technicians, sales reps, and office staff
Notes	View notes on a customer
Routes	View technician routes for a date
Payments	View payment history (payment method details are masked)
Regions, offices, service types, cancellation reasons	View how your account is configured
Chemical/product records	View what was applied on an appointment (compliance/reporting)
Documents	View files attached to a customer
Flags & tasks	View labels and to-dos assigned to records

39 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 FieldRoutes 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 front-desk and dispatch actions):

What it covers	Examples of what it can do
Customers	Add or update a customer
Appointments	Schedule, reschedule, cancel, or mark an appointment complete
Invoices (tickets)	Create an invoice, add/edit line items
Recurring service plans (subscriptions)	Set up or update a customer's recurring service
Notes	Add or update a note
Routes	Build or update a technician route
Documents	Upload or update a document
Flags & tasks	Assign a flag, create or update a task

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

• Deleting an invoice, invoice line item, note, document, or flag assignment
• Creating or updating employee records (kept separate from front-desk work since it touches HR/access data)
• Anything involving payments or stored card/ACH details — recording a payment (which can trigger a real charge), issuing a refund, or creating/updating/deleting a stored payment method. This entire area stays admin-only, including just viewing stored payment profiles (office-ops can view basic payment history, but not the stored card/ACH profiles themselves)

How to set it up

You'll need:

• A computer with Node.js installed (free software this project runs on)
• A FieldRoutes/PestRoutes account with API access provisioned (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-fieldroutes.git
cd backcrew-mcp-fieldroutes
npm install
npm run build

Step 2: Get your FieldRoutes API credentials

Unlike some platforms, FieldRoutes doesn't have a self-service "generate a key" button — you'll need to ask for access directly.

1. Contact your FieldRoutes account rep or FieldRoutes support and ask for API access
2. They'll give you three things: your subdomain (the company-name part of your FieldRoutes login URL), an authentication key, and an authentication token

Reference docs: fieldroutes.dev/documentation.

Step 3: Save your credentials and choose your safety level

cp .env.example .env

Open the new .env file in any text editor:

FIELDROUTES_SUBDOMAIN=your_subdomain_here
FIELDROUTES_AUTH_KEY=your_key_here
FIELDROUTES_AUTH_TOKEN=your_token_here

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

Save the file. Keep it private — anyone with these credentials can access your FieldRoutes 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": {
    "fieldroutes": {
      "command": "node",
      "args": ["/absolute/path/to/backcrew-mcp-fieldroutes/dist/index.js"],
      "env": {
        "FIELDROUTES_SUBDOMAIN": "your_subdomain_here",
        "FIELDROUTES_AUTH_KEY": "your_key_here",
        "FIELDROUTES_AUTH_TOKEN": "your_token_here",
        "FR_MCP_MODE": "read_only",
        "FR_MCP_PROFILE": "readonly-owner"
      }
    }
  }
}

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

Restart Claude. You should see FieldRoutes 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 customer named Dana Ruiz"
• "What appointments are on the schedule for tomorrow?"
• "Show me the invoices for this customer"
• "What chemical was applied on the last visit to this address?"

If you later turn on office-ops:

• "Schedule a follow-up appointment for this customer next Tuesday morning"
• "Create an invoice for today's visit"
• "Add a note that the gate code changed"
• "Cancel tomorrow's appointment for this customer — they called to reschedule"

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 customer first. Create a test customer named something obvious like "ZZZ Test Customer — 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, employee-record changes, and anything payment-related are hard or impossible to undo, and payments can move real money. office-ops covers real day-to-day work without exposing any of that.
4. Never share your authentication key or token — in chat, in a screenshot, in a support ticket, anywhere. Treat them like a password, because they function like one.
5. If something looks wrong, switch back to FR_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 FieldRoutes API operation it maps to and its access tier (e.g. Maps to POST /appointment/create. [tier: office-ops]). Each domain lives in its own file under src/tools/.

The tier/profile system

Every call to registerJsonTool(...) declares a tier: "readonly-owner" | "office-ops" | "admin". At startup, src/toolkit.ts reads FR_MCP_MODE and FR_MCP_PROFILE once, computes the maximum exposed tier, and any tool above that tier is never registered with the MCP server — it doesn't just get hidden from a menu, it's genuinely absent from tools/list and can't be called. FR_MCP_MODE=read_only always wins over FR_MCP_PROFILE regardless of what the profile is set to; only read_write lets the profile setting take effect. An unrecognized profile value falls back to readonly-owner, not the most permissive tier. This is the same pattern used in backcrew-mcp (Housecall Pro) — see that repo's README for the original writeup.

Project layout

src/
  index.ts          Server entrypoint — registers every tool group and starts stdio transport
  client.ts          Minimal fetch-based FieldRoutes API client (query-string auth, form-encoded body, error handling)
  toolkit.ts          Tier/profile-aware helper that wires a Zod input schema + handler into an MCP tool
  tools/
    customers.ts
    appointments.ts
    tickets.ts        (invoices)
    subscriptions.ts  (recurring service plans)
    employees.ts
    notes.ts
    routes.ts
    payments.ts
    reference.ts       (regions, offices, service types, cancellation reasons)
    chemicals.ts
    documents.ts
    flags.ts
    tasks.ts

Notes on the FieldRoutes API

• Base URL: https://{your-subdomain}.pestroutes.com/api/{resource}/{operation} — FieldRoutes was formerly PestRoutes, and the API still runs on the pestroutes.com domain.
• Auth: authenticationKey and authenticationToken as query-string parameters on every request (not headers).
• Most resources follow a search-then-get pattern: {resource}/search takes filters and returns a plain array of matching IDs (no result limit), then {resource}/get takes an array of up to 1000 IDs and returns the full records. This project's search_* and get_* tool pairs mirror that directly rather than hiding it behind a single call, since that's the real shape of the API.
• Search filters support an advanced {"operator": ">", "value": ...} query-object syntax on most date/numeric fields (operators: >, <, >=, <=, =, !=, IN, BETWEEN, LIKE, STARTSWITH, ENDSWITH, CONTAINS). Every search_* tool exposes an extra_filters field for this.
• Full reference: fieldroutes.dev/documentation

This server was built by reading FieldRoutes' public API documentation directly. One caveat worth flagging: the docs page doesn't include a dedicated "Authentication" walkthrough with a worked example — the query-string authenticationKey/authenticationToken pattern and the {subdomain}.pestroutes.com base URL were confirmed from FieldRoutes' own live documentation sandbox URL and corroborating third-party integration docs (Domo's PestRoutes connector), not from an explicit code sample on fieldroutes.dev itself. If your first live call doesn't authenticate, this is the first thing to double-check against what FieldRoutes support gives you.

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

FieldRoutes' API covers 30+ resources; this repo covers the 13 most central to day-to-day pest control operations (81 tools). Not yet covered: access control profiles, application methods, appointment reminders, changelogs, customer flags, doors/knocks (door-to-door sales tracking), forms, GL accounts, groups, insects (reference data), locations, reviews, spots (route stop slots), teams, time clock, and units. 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