# Halo PSA MCP Server

An MCP (Model Context Protocol) server that connects AI assistants to your Halo PSA instance, giving you natural-language access to tickets, clients, contracts, invoices, projects, assets, and revenue analytics.

## Key Features

- **Tickets & Actions** — Search, filter, and inspect tickets; view time entries and SLA status
- **Clients & Sites** — Browse customers, their sites, and contacts
- **Contracts** — View active contracts representing recurring managed services
- **Invoices (Recurring vs One-off)** — Separately query recurring invoices (MRR) and ad-hoc invoices
- **Revenue Breakdown** — Composite tool that categorises recurring vs non-recurring revenue per client
- **Projects** — View project status, budgets, and associated work
- **Assets** — Browse configuration items and their associations
- **Agents & Teams** — See who's working on what

## Prerequisites

- A Halo PSA instance with API access enabled
- An API application configured with **Client ID and Secret (Services)** auth method
- Docker (for container deployment) or Node.js 20+ (for local dev)

## Setup: Creating API Credentials in Halo

1. Log into your Halo PSA instance as an admin
2. Navigate to **Configuration > Integrations > Halo PSA API**
3. Click **View Applications** > **New**
4. Set the authentication method to **Client ID and Secret (Services)**
5. Under **Permissions**, grant read access to the scopes you need:
   - `read:tickets` — Tickets and actions
   - `read:customers` — Clients and sites
   - `read:contracts` — Contracts
   - `read:invoices` — Invoices (recurring and one-off)
   - `read:projects` — Projects
   - `read:assets` — Assets
   - `read:crm` — CRM / reporting data
6. Save and note down the **Client ID** and **Client Secret**
7. Note your **instance URL** (e.g. `https://yourcompany.halopsa.com`)

## Quick Start with Docker

### Build the image

docker build -t halo-psa-mcp .

### Run interactively (for testing)

docker run -it --rm \
  -e HALO_INSTANCE_URL=https://yourcompany.halopsa.com \
  -e HALO_CLIENT_ID=your-client-id \
  -e HALO_CLIENT_SECRET=your-client-secret \
  halo-psa-mcp

## Connecting to Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "halo-psa": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "HALO_INSTANCE_URL=https://yourcompany.halopsa.com",
        "-e", "HALO_CLIENT_ID=your-client-id",
        "-e", "HALO_CLIENT_SECRET=your-client-secret",
        "halo-psa-mcp"
      ]
    }
  }
}

## Connecting to Claude Code

claude mcp add halo-psa \
  -- docker run -i --rm \
  -e HALO_INSTANCE_URL=https://yourcompany.halopsa.com \
  -e HALO_CLIENT_ID=your-client-id \
  -e HALO_CLIENT_SECRET=your-client-secret \
  halo-psa-mcp

## Available Tools

| Tool | Description |
|------|-------------|
| `list_tickets` | Search/filter tickets by client, agent, status, type, team, priority |
| `get_ticket` | Full ticket details with actions/notes |
| `list_clients` | Browse customers with search |
| `get_client` | Client details with sites |
| `list_contracts` | Active contracts (recurring services) |
| `get_contract` | Contract details with billing lines |
| `list_invoices` | One-off/ad-hoc invoices (non-recurring charges) |
| `get_invoice` | Invoice line item details |
| `list_recurring_invoices` | Recurring invoices (MRR/recurring revenue) |
| `get_recurring_invoice` | Recurring invoice schedule and lines |
| `list_projects` | Projects with status/budget |
| `get_project` | Full project details |
| `list_actions` | Time entries, notes, billable work |
| `list_assets` | Configuration items / assets |
| `get_asset` | Asset details and associations |
| `revenue_breakdown` | **Recurring vs non-recurring revenue analysis** per client |
| `list_agents` | Technicians and team members |
| `list_reports` | Available Halo reports |

## Recurring vs Non-Recurring Revenue

The `revenue_breakdown` tool is specifically designed to answer the question: "What is recurring vs non-recurring for this customer?"

It combines:
- **Recurring Invoices** — scheduled auto-billing (monthly/quarterly/annual managed services)
- **Contracts** — recurring service agreements with billing terms
- **Standard Invoices** — one-off project work, ad-hoc charges, break-fix billing

## License

MIT