# HaloPSA

HaloPSA is a Claude Code MCP server that links assistants to the HaloPSA REST API. Automates tickets, customer records, and billing inside agent chat.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5 repo stars
- Author: WYRE-AI
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/WYRE-AI/halopsa-mcp
- Updated: 2026-11-16
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/halopsa

## What it does

The server links your coding assistant to HaloPSA services covering support tickets, customer accounts, hardware assets, and invoices. It relies on a decision tree model instead of registering every tool upfront: assistants invoke `halopsa_navigate` first to choose a target domain, which loads only the relevant tools on demand.

Ticket management covers issue creation, list filters, and adding activity notes with duration logged via `time_minutes`. Running the prebuilt Docker container requires OAuth 2.0 credentials (`HALOPSA_CLIENT_ID` and `HALOPSA_CLIENT_SECRET`) plus your instance identifier in `HALOPSA_TENANT` or `HALOPSA_BASE_URL`. If installed through npm directly, builds will fail without a GitHub Personal Access Token scoped to `read:packages`.

## Requirements
- Needs: Docker
- Environment variables: `HALOPSA_CLIENT_ID`, `HALOPSA_CLIENT_SECRET`, `HALOPSA_TENANT`, `HALOPSA_BASE_URL`, `MCP_TRANSPORT`, `AUTH_MODE`, `LOG_LEVEL` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env HALOPSA_CLIENT_ID=<HALOPSA_CLIENT_ID> --env HALOPSA_CLIENT_SECRET=<HALOPSA_CLIENT_SECRET> --env HALOPSA_TENANT=<HALOPSA_TENANT> --env HALOPSA_BASE_URL=<HALOPSA_BASE_URL> --env MCP_TRANSPORT=<MCP_TRANSPORT> --transport stdio halopsa -- docker run -i --rm -e HALOPSA_CLIENT_ID -e HALOPSA_CLIENT_SECRET -e HALOPSA_TENANT -e HALOPSA_BASE_URL -e MCP_TRANSPORT ghcr.io/wyre-ai/halopsa-mcp:v1.8.4
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Codex

**Platform CLI**
```bash
codex mcp add halopsa --env HALOPSA_CLIENT_ID=<HALOPSA_CLIENT_ID> --env HALOPSA_CLIENT_SECRET=<HALOPSA_CLIENT_SECRET> --env HALOPSA_TENANT=<HALOPSA_TENANT> --env HALOPSA_BASE_URL=<HALOPSA_BASE_URL> --env MCP_TRANSPORT=<MCP_TRANSPORT> -- docker run -i --rm -e HALOPSA_CLIENT_ID -e HALOPSA_CLIENT_SECRET -e HALOPSA_TENANT -e HALOPSA_BASE_URL -e MCP_TRANSPORT ghcr.io/wyre-ai/halopsa-mcp:v1.8.4
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "halopsa": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "HALOPSA_CLIENT_ID",
                "-e",
                "HALOPSA_CLIENT_SECRET",
                "-e",
                "HALOPSA_TENANT",
                "-e",
                "HALOPSA_BASE_URL",
                "-e",
                "MCP_TRANSPORT",
                "ghcr.io/wyre-ai/halopsa-mcp:v1.8.4"
            ],
            "env": {
                "HALOPSA_CLIENT_ID": "<HALOPSA_CLIENT_ID>",
                "HALOPSA_CLIENT_SECRET": "<HALOPSA_CLIENT_SECRET>",
                "HALOPSA_TENANT": "<HALOPSA_TENANT>",
                "HALOPSA_BASE_URL": "<HALOPSA_BASE_URL>",
                "MCP_TRANSPORT": "<MCP_TRANSPORT>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "halopsa": {
            "type": "stdio",
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-e",
                "HALOPSA_CLIENT_ID",
                "-e",
                "HALOPSA_CLIENT_SECRET",
                "-e",
                "HALOPSA_TENANT",
                "-e",
                "HALOPSA_BASE_URL",
                "-e",
                "MCP_TRANSPORT",
                "ghcr.io/wyre-ai/halopsa-mcp:v1.8.4"
            ],
            "env": {
                "HALOPSA_CLIENT_ID": "<HALOPSA_CLIENT_ID>",
                "HALOPSA_CLIENT_SECRET": "<HALOPSA_CLIENT_SECRET>",
                "HALOPSA_TENANT": "<HALOPSA_TENANT>",
                "HALOPSA_BASE_URL": "<HALOPSA_BASE_URL>",
                "MCP_TRANSPORT": "<MCP_TRANSPORT>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e HALOPSA_CLIENT_ID=<HALOPSA_CLIENT_ID> -e HALOPSA_CLIENT_SECRET=<HALOPSA_CLIENT_SECRET> -e HALOPSA_TENANT=<HALOPSA_TENANT> -e HALOPSA_BASE_URL=<HALOPSA_BASE_URL> -e MCP_TRANSPORT=<MCP_TRANSPORT> halopsa docker run -i --rm -e HALOPSA_CLIENT_ID -e HALOPSA_CLIENT_SECRET -e HALOPSA_TENANT -e HALOPSA_BASE_URL -e MCP_TRANSPORT ghcr.io/wyre-ai/halopsa-mcp:v1.8.4
```
Replace <…> with your own values. 2 more environment variables are in the server README

## When to use it
- create and update service desk tickets inside HaloPSA
- log billable work duration on tickets using `time_minutes`
- search company profiles and inspect linked IT assets
- pull invoice details and inspect technician team assignments

## Example prompts
- Run halopsa_navigate to switch context to the tickets domain
- Search HaloPSA clients for Acme Corp and show active assets
- Log 45 minutes of troubleshooting on ticket 5012 with an action note

## Similar
- [HaloPSA MCP](https://affpapa.org/en/nevibecode/mcp/halopsa-mcp.md) — MCP server · ★ 87 repo stars
- [ConnectWise Manage](https://affpapa.org/en/nevibecode/mcp/connectwise-manage.md) — MCP server · ★ 32 repo stars
- [ConnectWise PSA](https://affpapa.org/en/nevibecode/mcp/connectwise-psa.md) — MCP server · ★ 7 repo stars
- [helpdesk-automation](https://affpapa.org/en/nevibecode/skills/helpdesk-automation.md) — skill · 124 installs
- [TehProf.kz Support](https://affpapa.org/en/nevibecode/mcp/tehprofkz-support.md) — MCP server
- [Zendesk Automation](https://affpapa.org/en/nevibecode/skills/zendesk-automation.md) — skill · 4700 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
