# 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

```bash
pip install fieldroutes_mcp
```

## Configure

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

```bash
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`:

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

```bash
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](LICENSE).