fieldroutes_mcp

MCP server for the FieldRoutes pest-control / lawn-care operations platform — talk to your data from Claude, Cursor, or any MCP client.

FieldRoutes (a ServiceTitan company) is used by 1,700+ pest-control, lawn-care, and pool-care companies to manage customers, recurring service subscriptions, appointments, routes, and invoices. This server wraps their public API and exposes it through the Model Context Protocol.

What you can do with it

You:   "Find every customer with an unpaid balance older than 30 days."
Claude: *calls search_customers with balance_min + balance_age_days filters*

You:   "Cancel tomorrow's appointment for customer 12345 — they just called."
Claude: *calls cancel_appointment with a reason string*

You:   "Add a note to ticket 67890 that says 'follow up next week'."
Claude: *calls create_note with entity='ticket', entity_id=67890*

Tools exposed

Tool	Purpose
health_check	Verify credentials work
search_customers	Filter by name, phone, email, balance, balance age, office
get_customer	Fetch one customer record
create_customer	Create a new customer record
update_customer	Update arbitrary customer fields
search_appointments	Filter by customer, date range, status
cancel_appointment	Cancel with reason
search_subscriptions	Recurring pest-control / lawn-care contracts
search_routes	Service routes by date / office
search_tickets	Invoices (FieldRoutes calls them "tickets")
create_note	Attach a note to any entity (customer/ticket/appointment)

11 tools covering the most-used FieldRoutes workflows.

Install

pip install fieldroutes_mcp

Configure

Generate an API key pair at https://app.fieldroutes.com (Settings -> API). Both fields are required on every request.

export FIELDROUTES_MCP_AUTHENTICATION_KEY="your-key-here"
export FIELDROUTES_MCP_AUTHENTICATION_TOKEN="your-token-here"

Use with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "fieldroutes_mcp": {
      "command": "fieldroutes_mcp",
      "env": {
        "FIELDROUTES_MCP_AUTHENTICATION_KEY": "...",
        "FIELDROUTES_MCP_AUTHENTICATION_TOKEN": "..."
      }
    }
  }
}

How it works

FieldRoutes' public API is a single endpoint that takes POST requests in the shape /{entity}/{action} with a JSON body containing the operation parameters plus authentication fields. Every response uses a {success, result, errorMessage} envelope.

This server wraps that pattern in:

• A typed exception hierarchy (FieldRoutesAuthError, FieldRoutesNotFoundError, FieldRoutesRateLimitError, FieldRoutesConnectionError, FieldRoutesAPIError).
• Exponential-backoff retry on 429/5xx.
• One-JSONL-line-per-call audit logging to stderr or a file via FIELDROUTES_MCP_AUDIT_LOG.

Development

git clone https://github.com/sanjibani/fieldroutes_mcp.git
cd fieldroutes_mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest
ruff check src tests
mypy src tests

License

MIT — see LICENSE.