# Jobber MCP Connector

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that connects Claude to [Jobber](https://getjobber.com) — the field service management platform. Manage clients, jobs, invoices, quotes, and scheduling through natural language.

Built by [Total Property Solutions Pro](https://totalproperty.solutions).

---

## What You Can Do

Once connected, you can ask Claude things like:

- _"Show me all active jobs this week"_
- _"Create a client for John Smith at 123 Main St"_
- _"What's on the schedule for tomorrow?"_
- _"Create a quote for roof cleaning at $350 for the Johnsons"_
- _"Mark job #142 as completed"_
- _"List all unpaid invoices"_
- _"Create an invoice for job #142 due in 30 days"_

---

## Tools Available

| Tool | Description |
|------|-------------|
| `jobber_list_clients` | List clients with name, email, phone, address |
| `jobber_create_client` | Create a new client |
| `jobber_list_jobs` | List jobs filtered by status |
| `jobber_create_job` | Create a new job/work order |
| `jobber_update_job_status` | Move a job through workflow stages |
| `jobber_list_invoices` | List invoices filtered by status |
| `jobber_create_invoice` | Create an invoice for a client or job |
| `jobber_list_quotes` | List quotes filtered by status |
| `jobber_create_quote` | Create a new quote with line items |
| `jobber_get_schedule` | Get today's, tomorrow's, or this week's schedule |

---

## Prerequisites

- [Node.js](https://nodejs.org) v18 or later
- A [Jobber](https://getjobber.com) account
- A Jobber Developer App (free — see setup below)
- [Claude Desktop](https://claude.ai/download) or another MCP-compatible client

---

## Installation

```bash
git clone https://github.com/totalproperty/jobber-mcp-connector.git
cd jobber-mcp-connector
npm install
```

---

## Configuration

### Step 1 — Create a Jobber Developer App

1. Go to [developer.getjobber.com](https://developer.getjobber.com) and sign in
2. Click **Create App**
3. Set the **Redirect URI** to `http://localhost:3100/callback`
4. Copy your **Client ID** and **Client Secret**

### Step 2 — Set Up Environment Variables

```bash
cp .env.example .env
```

Edit `.env` with your credentials:

```env
JOBBER_CLIENT_ID=your_client_id_here
JOBBER_CLIENT_SECRET=your_client_secret_here
```

### Step 3 — Authorize via OAuth2

Run the included helper to get your access and refresh tokens:

```bash
JOBBER_CLIENT_ID=your_id JOBBER_CLIENT_SECRET=your_secret node src/oauth-helper.js
```

This will:
1. Print an authorization URL — open it in your browser
2. After you approve the app in Jobber, it captures the callback automatically
3. Print your `JOBBER_ACCESS_TOKEN` and `JOBBER_REFRESH_TOKEN`

Add both tokens to your `.env` file.

### Step 4 — Configure Claude Desktop

Add this to your Claude Desktop MCP config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "jobber": {
      "command": "node",
      "args": ["/absolute/path/to/jobber-mcp-connector/src/index.js"],
      "env": {
        "JOBBER_CLIENT_ID": "your_client_id",
        "JOBBER_CLIENT_SECRET": "your_client_secret",
        "JOBBER_ACCESS_TOKEN": "your_access_token",
        "JOBBER_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}
```

Restart Claude Desktop. The Jobber tools will appear automatically.

---

## Usage Examples

### List today's schedule
> _"What's on my schedule today?"_

### Create a client
> _"Add a new client: Sarah Johnson, sarah@email.com, (555) 867-5309, 456 Oak Ave, Tampa FL 33601"_

### Create a quote
> _"Create a quote for Sarah Johnson for pressure washing her driveway — 2 hours at $95/hr"_

### Check unpaid invoices
> _"Show me all invoices that haven't been paid yet"_

### Update job status
> _"Mark job #204 as completed"_

---

## Token Refresh

Access tokens expire periodically. The connector automatically refreshes them using your `JOBBER_REFRESH_TOKEN`. If you see authentication errors, re-run the OAuth helper to get fresh tokens.

---

## Development

```bash
# Run with auto-reload on file changes
npm run dev

# Run normally
npm start
```

---

## Project Structure

```
jobber-mcp-connector/
├── src/
│   ├── index.js          # MCP server entry point
│   ├── jobber-client.js  # GraphQL API client + OAuth2
│   ├── queries.js        # All GraphQL queries and mutations
│   ├── tools.js          # Tool definitions and handlers
│   └── oauth-helper.js   # One-time OAuth2 authorization helper
├── .env.example          # Environment variable template
├── package.json
└── README.md
```

---

## License

MIT — Built by [Total Property Solutions Pro](https://totalproperty.solutions)