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