mcpengine/servers/jobber/README.md

Jobber MCP Server

A comprehensive Model Context Protocol (MCP) server for the Jobber field service management platform. This server provides 96 GraphQL-powered tools and 15 React-based applications for complete business operations management.

Table of Contents

• Overview
• Installation
• Configuration
• Available Tools (96)
  • Client Management (7 tools)
  • Job Management (8 tools)
  • Quote Management (8 tools)
  • Invoice Management (7 tools)
  • Scheduling & Visits (6 tools)
  • Team Management (4 tools)
  • Expense Tracking (5 tools)
  • Product Catalog (5 tools)
  • Service Requests (6 tools)
  • Reporting & Analytics (3 tools)
  • Property Management (6 tools)
  • Timesheet Management (7 tools)
  • Line Items (8 tools)
  • Form Builder (8 tools)
  • Tax Management (8 tools)
• React Applications (15)
• Usage Examples
• GraphQL API
• Development
• License

Overview

The Jobber MCP Server enables AI assistants and automation tools to interact with Jobber's complete field service management platform. It supports:

• Client & Property Management: Track customers, properties, and service history
• Job Lifecycle: From quotes to completion with full workflow support
• Scheduling: Manage visits, assignments, and team calendars
• Invoicing: Create, send, and track payments
• Team Management: Monitor team performance, timesheets, and utilization
• Forms: Build custom forms and capture submissions
• Reporting: Generate business insights and analytics

Installation

npm install @mcpengine/jobber-server

Or install from source:

git clone https://github.com/BusyBee3333/mcpengine.git
cd mcpengine/servers/jobber
npm install
npm run build

Configuration

Set your Jobber API token as an environment variable:

export JOBBER_API_TOKEN="your_api_token_here"

To obtain an API token:

1. Log into your Jobber account
2. Navigate to Settings > API Access
3. Generate a new API token with appropriate permissions

Available Tools

Client Management

7 tools for managing customer relationships:

1. list_clients - List all clients with optional filtering

   • Parameters: isArchived, limit, cursor
   • Returns paginated client list with contact details

2. get_client - Get a specific client by ID

   • Parameters: clientId
   • Returns full client details including contact info and billing address

3. create_client - Create a new client

   • Parameters: firstName, lastName, companyName, email, phone, billingAddress
   • Returns newly created client

4. update_client - Update existing client information

   • Parameters: clientId, firstName, lastName, companyName, email, phone, billingAddress
   • Returns updated client

5. archive_client - Archive a client

   • Parameters: clientId
   • Returns archived client status

6. search_clients - Search clients by name, email, or phone

   • Parameters: query, limit
   • Returns matching clients

7. list_client_properties - List all properties for a client

   • Parameters: clientId, limit, cursor
   • Returns paginated property list

Job Management

8 tools for complete job lifecycle management:

1. list_jobs - List all jobs with filtering

   • Parameters: status, clientId, limit, cursor
   • Returns paginated job list with status and details

2. get_job - Get detailed job information

   • Parameters: jobId
   • Returns complete job details including line items and visits

3. create_job - Create a new job

   • Parameters: title, description, clientId, propertyId, startAt, endAt
   • Returns newly created job

4. update_job - Update job information

   • Parameters: jobId, title, description, startAt, endAt, status
   • Returns updated job

5. close_job - Mark a job as complete

   • Parameters: jobId
   • Returns closed job status

6. create_job_visit - Schedule a visit for a job

   • Parameters: jobId, title, startAt, endAt, assignedUserIds
   • Returns created visit

7. list_job_visits - List all visits for a job

   • Parameters: jobId, limit, cursor
   • Returns paginated visit list

8. list_job_line_items - List all line items on a job

   • Parameters: jobId, limit, cursor
   • Returns job line items with pricing

Quote Management

8 tools for creating and managing quotes:

1. list_quotes - List all quotes

   • Parameters: status, clientId, limit, cursor
   • Returns paginated quote list

2. get_quote - Get detailed quote information

   • Parameters: quoteId
   • Returns complete quote with line items

3. create_quote - Create a new quote

   • Parameters: title, message, clientId, propertyId
   • Returns newly created quote

4. update_quote - Update quote details

   • Parameters: quoteId, title, message, status
   • Returns updated quote

5. send_quote - Send quote to client

   • Parameters: quoteId, recipientEmail
   • Returns send status

6. approve_quote - Approve a quote

   • Parameters: quoteId
   • Returns approved quote

7. convert_quote_to_job - Convert approved quote to job

   • Parameters: quoteId
   • Returns created job

8. list_quote_line_items - List all line items on a quote

   • Parameters: quoteId, limit, cursor
   • Returns quote line items

Invoice Management

7 tools for billing and payments:

1. list_invoices - List all invoices

   • Parameters: status, clientId, limit, cursor
   • Returns paginated invoice list

2. get_invoice - Get detailed invoice information

   • Parameters: invoiceId
   • Returns complete invoice with line items and payments

3. create_invoice - Create a new invoice

   • Parameters: jobId, subject, message, issueDate, dueDate
   • Returns newly created invoice

4. send_invoice - Send invoice to client

   • Parameters: invoiceId, recipientEmail
   • Returns send status

5. mark_invoice_paid - Mark invoice as paid

   • Parameters: invoiceId, amount, paymentDate, method
   • Returns payment record

6. create_payment - Record a payment

   • Parameters: invoiceId, amount, paymentDate, method, reference
   • Returns payment details

7. list_invoice_payments - List payments for an invoice

   • Parameters: invoiceId, limit, cursor
   • Returns payment history

Scheduling & Visits

6 tools for managing schedules and field visits:

1. list_visits - List all scheduled visits

   • Parameters: startDate, endDate, status, limit, cursor
   • Returns paginated visit list

2. get_visit - Get detailed visit information

   • Parameters: visitId
   • Returns complete visit details with assignments

3. create_visit - Create a new visit

   • Parameters: jobId, title, startAt, endAt, assignedUserIds
   • Returns created visit

4. update_visit - Update visit details

   • Parameters: visitId, title, startAt, endAt, status
   • Returns updated visit

5. complete_visit - Mark visit as complete

   • Parameters: visitId, completionNotes
   • Returns completed visit

6. list_visit_assignments - List team member assignments for visits

   • Parameters: visitId, limit
   • Returns assigned team members

Team Management

4 tools for managing your field service team:

1. list_users - List all team members

   • Parameters: isActive, limit, cursor
   • Returns paginated user list

2. get_user - Get detailed user information

   • Parameters: userId
   • Returns user details and role information

3. get_team_utilization_report - Get team utilization metrics

   • Parameters: startDate, endDate, userIds
   • Returns utilization statistics

4. get_user_timesheet - Get timesheet for a user

   • Parameters: userId, startDate, endDate
   • Returns time entries and totals

Expense Tracking

5 tools for managing business expenses:

1. list_expenses - List all expenses

   • Parameters: status, userId, startDate, endDate, limit, cursor
   • Returns paginated expense list

2. get_expense - Get detailed expense information

   • Parameters: expenseId
   • Returns expense details with attachments

3. create_expense - Create a new expense

   • Parameters: description, amount, category, date, userId
   • Returns created expense

4. update_expense - Update expense details

   • Parameters: expenseId, description, amount, category, status
   • Returns updated expense

5. delete_expense - Delete an expense

   • Parameters: expenseId
   • Returns deletion confirmation

Product Catalog

5 tools for managing products and services:

1. list_products - List all products

   • Parameters: isActive, limit, cursor
   • Returns paginated product list

2. get_product - Get detailed product information

   • Parameters: productId
   • Returns product details with pricing

3. create_product - Create a new product

   • Parameters: name, description, unitPrice, unit, taxable
   • Returns created product

4. update_product - Update product details

   • Parameters: productId, name, description, unitPrice, isActive
   • Returns updated product

5. delete_product - Delete a product

   • Parameters: productId
   • Returns deletion confirmation

Service Requests

6 tools for managing incoming service requests:

1. list_requests - List all service requests

   • Parameters: status, limit, cursor
   • Returns paginated request list

2. get_request - Get detailed request information

   • Parameters: requestId
   • Returns request details and contact info

3. create_request - Create a new service request

   • Parameters: title, description, clientName, clientEmail, clientPhone
   • Returns created request

4. update_request - Update request status and details

   • Parameters: requestId, status, notes
   • Returns updated request

5. convert_request_to_quote - Convert request to quote

   • Parameters: requestId
   • Returns created quote

6. convert_request_to_job - Convert request directly to job

   • Parameters: requestId
   • Returns created job

Reporting & Analytics

3 tools for business intelligence:

1. get_revenue_report - Generate revenue report

   • Parameters: startDate, endDate, groupBy
   • Returns revenue metrics and trends

2. get_job_profit_report - Get job profitability analysis

   • Parameters: startDate, endDate, clientId
   • Returns profit margins and costs

3. get_team_utilization_report - Analyze team productivity

   • Parameters: startDate, endDate, userIds
   • Returns utilization percentages and billable hours

Property Management

6 tools for managing service locations:

1. list_properties - List all properties

   • Parameters: clientId, limit, cursor
   • Returns paginated property list

2. get_property - Get detailed property information

   • Parameters: propertyId
   • Returns property details and address

3. create_property - Create a new property

   • Parameters: clientId, address, city, province, postalCode, country
   • Returns created property

4. update_property - Update property details

   • Parameters: propertyId, address, city, province, postalCode
   • Returns updated property

5. delete_property - Delete a property

   • Parameters: propertyId
   • Returns deletion confirmation

6. set_default_property - Set default property for a client

   • Parameters: clientId, propertyId
   • Returns updated client

Timesheet Management

7 tools for tracking team time:

1. list_time_entries - List all time entries

   • Parameters: userId, startDate, endDate, limit, cursor
   • Returns paginated time entry list

2. get_time_entry - Get detailed time entry information

   • Parameters: timeEntryId
   • Returns time entry with job details

3. create_time_entry - Create a new time entry

   • Parameters: userId, jobId, startTime, endTime, description
   • Returns created time entry

4. update_time_entry - Update time entry details

   • Parameters: timeEntryId, startTime, endTime, description
   • Returns updated time entry

5. delete_time_entry - Delete a time entry

   • Parameters: timeEntryId
   • Returns deletion confirmation

6. stop_time_entry - Stop a running time entry

   • Parameters: timeEntryId
   • Returns stopped time entry

7. get_user_timesheet - Get complete timesheet for a user

   • Parameters: userId, startDate, endDate
   • Returns all time entries and totals

Line Items

8 tools for managing quote/job/invoice line items:

1. create_job_line_item - Add line item to job

   • Parameters: jobId, name, description, quantity, unitPrice
   • Returns created line item

2. create_quote_line_item - Add line item to quote

   • Parameters: quoteId, name, description, quantity, unitPrice
   • Returns created line item

3. create_invoice_line_item - Add line item to invoice

   • Parameters: invoiceId, name, description, quantity, unitPrice
   • Returns created line item

4. update_line_item - Update line item details

   • Parameters: lineItemId, name, description, quantity, unitPrice
   • Returns updated line item

5. delete_line_item - Delete a line item

   • Parameters: lineItemId
   • Returns deletion confirmation

6. reorder_line_items - Change line item order

   • Parameters: lineItemIds (ordered array)
   • Returns reordered items

7. duplicate_line_item - Copy a line item

   • Parameters: lineItemId
   • Returns duplicated item

8. bulk_update_line_items - Update multiple line items

   • Parameters: updates (array of updates)
   • Returns updated items

Form Builder

8 tools for creating and managing custom forms:

1. list_forms - List all forms

   • Parameters: limit, cursor
   • Returns paginated form list

2. get_form - Get form definition

   • Parameters: formId
   • Returns form with all fields

3. create_form - Create a new form

   • Parameters: name, fields (array)
   • Returns created form

4. update_form - Update form definition

   • Parameters: formId, name, fields
   • Returns updated form

5. delete_form - Delete a form

   • Parameters: formId
   • Returns deletion confirmation

6. submit_form - Submit form data

   • Parameters: formId, data (field values)
   • Returns submission record

7. list_form_submissions - List all submissions for a form

   • Parameters: formId, limit, cursor
   • Returns paginated submissions

8. get_form_submission - Get detailed submission

   • Parameters: submissionId
   • Returns submission with all field values

Tax Management

8 tools for managing taxes and tax calculations:

1. list_taxes - List all tax rates

   • Parameters: isActive, limit, cursor
   • Returns paginated tax list

2. get_tax - Get tax details

   • Parameters: taxId
   • Returns tax rate and settings

3. create_tax - Create a new tax

   • Parameters: name, rate, isCompound
   • Returns created tax

4. update_tax - Update tax details

   • Parameters: taxId, name, rate, isActive
   • Returns updated tax

5. delete_tax - Delete a tax

   • Parameters: taxId
   • Returns deletion confirmation

6. apply_tax_to_line_item - Apply tax to a line item

   • Parameters: lineItemId, taxId
   • Returns updated line item

7. remove_tax_from_line_item - Remove tax from line item

   • Parameters: lineItemId, taxId
   • Returns updated line item

8. calculate_tax_total - Calculate total tax amount

   • Parameters: lineItemIds, taxIds
   • Returns calculated tax breakdown

React Applications

15 Interactive Web Applications

All applications are built with React 18, TypeScript, and Tailwind CSS. Each app is production-ready and fully functional.

1. Client Dashboard

Path: src/ui/react-app/src/apps/client-dashboard/

View and manage all clients with revenue and job statistics. Features:

• Client list with search and filtering
• Revenue tracking per client
• Job count and status overview
• Quick access to client details

2. Client Detail

Path: src/ui/react-app/src/apps/client-detail/

Comprehensive client profile view with:

• Complete contact information
• Property list
• Job history
• Revenue metrics
• Quick actions for creating quotes/jobs

3. Expense Manager

Path: src/ui/react-app/src/apps/expense-manager/

Track and approve team expenses:

• Filter by status (pending/approved/rejected)
• Category-based organization
• Attachment support
• Approval workflow

4. Financial Dashboard

Path: src/ui/react-app/src/apps/financial-dashboard/

Business financial overview:

• Total revenue and expenses
• Net profit calculation
• Outstanding vs paid invoices
• Monthly growth metrics
• Collection rate tracking

5. Form Builder

Path: src/ui/react-app/src/apps/form-builder/

Visual form designer with:

• Drag-and-drop field management
• Multiple field types (text, select, textarea, checkbox, date)
• Required field configuration
• Live preview
• Form submission handling

6. Invoice Dashboard

Path: src/ui/react-app/src/apps/invoice-dashboard/

Invoice management interface:

• Invoice list with status filtering
• Payment tracking
• Quick send and payment actions
• Client and amount details

7. Job Board

Path: src/ui/react-app/src/apps/job-board/

Visual job management board:

• Kanban-style job organization
• Status-based filtering (quoted, scheduled, in progress, completed)
• Job cards with key metrics
• Quick status updates

8. Job Detail

Path: src/ui/react-app/src/apps/job-detail/

Comprehensive job view:

• Job information and timeline
• Line items and pricing
• Visit schedule
• Client and property details
• Status management

9. Property Map

Path: src/ui/react-app/src/apps/property-map/

Geographic property visualization:

• Interactive map view
• Property markers with job counts
• Property list panel
• Client information
• Click to select and view details

10. Quote Builder

Path: src/ui/react-app/src/apps/quote-builder/

Create and edit quotes:

• Client selection
• Line item management
• Pricing calculator
• Tax application
• Quote preview

11. Request Inbox

Path: src/ui/react-app/src/apps/request-inbox/

Service request management:

• Request status workflow (new, contacted, quoted, converted)
• Priority indicators
• Client contact information
• Quick actions (contact, quote, convert)

12. Schedule Calendar

Path: src/ui/react-app/src/apps/schedule-calendar/

Visual scheduling interface:

• Day/week calendar view
• Visit timeline visualization
• Team member assignments
• Status tracking (scheduled, in progress, completed)
• Time slot management

13. Team Overview

Path: src/ui/react-app/src/apps/team-overview/

Team performance dashboard:

• Team member list
• Active and completed job counts
• Weekly hours tracking
• Availability status
• Performance metrics

14. Timesheet Grid

Path: src/ui/react-app/src/apps/timesheet-grid/

Time entry management:

• Tabular timesheet view
• Approval workflow
• Filter by status (pending/approved)
• Employee and job details
• Hours calculation

15. Visit Tracker

Path: src/ui/react-app/src/apps/visit-tracker/

Field visit tracking:

• Visit status workflow (scheduled, en route, in progress, completed)
• Client and location details
• Team assignments
• Notes and completion tracking
• Quick status updates

Usage Examples

Basic Connection

import { JobberServer } from '@mcpengine/jobber-server';

const server = new JobberServer();
await server.run();

Create Client and Job

// Create a new client
const client = await tools.create_client({
  firstName: "John",
  lastName: "Doe",
  companyName: "Doe Enterprises",
  email: "john@doeenterprises.com",
  phone: "555-0123"
});

// Create a job for the client
const job = await tools.create_job({
  title: "HVAC Installation",
  description: "Install new heating system",
  clientId: client.id,
  startAt: "2024-02-20T09:00:00Z",
  endAt: "2024-02-20T17:00:00Z"
});

Generate Quote and Convert to Job

// Create a quote
const quote = await tools.create_quote({
  title: "Kitchen Renovation",
  message: "As discussed, here is your quote",
  clientId: "client_123"
});

// Add line items
await tools.create_quote_line_item({
  quoteId: quote.id,
  name: "Cabinet Installation",
  quantity: 1,
  unitPrice: 2500
});

// Send to client
await tools.send_quote({
  quoteId: quote.id,
  recipientEmail: "client@example.com"
});

// After approval, convert to job
const job = await tools.convert_quote_to_job({
  quoteId: quote.id
});

Track Team Time

// Start time entry
const timeEntry = await tools.create_time_entry({
  userId: "user_123",
  jobId: "job_456",
  startTime: "2024-02-15T09:00:00Z",
  description: "Installation work"
});

// Stop when complete
await tools.stop_time_entry({
  timeEntryId: timeEntry.id
});

// Get user timesheet
const timesheet = await tools.get_user_timesheet({
  userId: "user_123",
  startDate: "2024-02-12",
  endDate: "2024-02-18"
});

Generate Reports

// Revenue report
const revenue = await tools.get_revenue_report({
  startDate: "2024-01-01",
  endDate: "2024-01-31",
  groupBy: "week"
});

// Team utilization
const utilization = await tools.get_team_utilization_report({
  startDate: "2024-02-01",
  endDate: "2024-02-29",
  userIds: ["user_1", "user_2", "user_3"]
});

GraphQL API

This server uses Jobber's GraphQL API. All tools execute GraphQL queries and mutations against the Jobber platform.

Authentication

API requests require a valid Jobber API token passed via the JOBBER_API_TOKEN environment variable.

Rate Limiting

Jobber implements rate limiting on API requests. This server respects those limits. For high-volume operations, consider:

• Batching requests
• Implementing retry logic
• Using pagination cursors

API Documentation

For complete Jobber GraphQL API documentation, visit: https://developer.getjobber.com/docs/

Development

Build from Source

# Clone repository
git clone https://github.com/BusyBee3333/mcpengine.git
cd mcpengine/servers/jobber

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run in development mode
npm run dev

TypeScript Compilation

# Type check without emitting
npx tsc --noEmit

# Build with source maps
npm run build

Project Structure

jobber/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server implementation
│   ├── clients/
│   │   └── jobber.ts         # GraphQL client
│   ├── tools/                # 15 tool modules (96 total tools)
│   │   ├── clients-tools.ts
│   │   ├── jobs-tools.ts
│   │   ├── quotes-tools.ts
│   │   ├── invoices-tools.ts
│   │   ├── scheduling-tools.ts
│   │   ├── team-tools.ts
│   │   ├── expenses-tools.ts
│   │   ├── products-tools.ts
│   │   ├── requests-tools.ts
│   │   ├── reporting-tools.ts
│   │   ├── properties-tools.ts
│   │   ├── timesheets-tools.ts
│   │   ├── line-items-tools.ts
│   │   ├── forms-tools.ts
│   │   └── taxes-tools.ts
│   └── ui/
│       └── react-app/
│           └── src/
│               └── apps/      # 15 React applications
│                   ├── client-dashboard/
│                   ├── client-detail/
│                   ├── expense-manager/
│                   ├── financial-dashboard/
│                   ├── form-builder/
│                   ├── invoice-dashboard/
│                   ├── job-board/
│                   ├── job-detail/
│                   ├── property-map/
│                   ├── quote-builder/
│                   ├── request-inbox/
│                   ├── schedule-calendar/
│                   ├── team-overview/
│                   ├── timesheet-grid/
│                   └── visit-tracker/
├── dist/                      # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details

---

Built with ❤️ using:

• Model Context Protocol
• Jobber GraphQL API
• TypeScript 5.7+
• React 18+
• Zod for validation

Part of the MCPEngine project - A comprehensive collection of MCP servers for business platforms.

For issues and support, visit: https://github.com/BusyBee3333/mcpengine/issues