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*

Related MCP server: housecallpro-mcp

Tools exposed

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.