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.
