Piers Macrae Cockram
57c191ee1f
TypeScript MCP server exposing 18 tools for querying a Halo PSA instance via OAuth 2.0 Client Credentials: - Tickets / actions (list, get, time entries) - Clients / sites (list, get) - Contracts (list, get — recurring service agreements) - Invoices — both one-off (list, get) and recurring (list, get) - Projects (list, get) - Assets / configuration items (list, get) - Agents, reports (list) - revenue_breakdown — composite tool that cross-references contracts, recurring invoices, and one-off invoices to separate recurring (MRR) from non-recurring revenue per client Build artefacts verified: npm install clean (0 vulnerabilities, 107 pkgs), npm run build produces dist/*.js with no TS errors, server boots and announces 'Halo PSA MCP server running on stdio'. Shipping with Dockerfile (multi-stage, alpine), .env.example, README.md (user-facing), and CLAUDE.md (deployment briefing for downstream Claude Code setup on customer machines). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
116 lines
4.3 KiB
Markdown
116 lines
4.3 KiB
Markdown
# 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
|