HaloPSA MCP Server

An MCP (Model Context Protocol) server that provides access to HaloPSA's reporting and REST APIs, allowing AI assistants to query and analyze HaloPSA data intelligently.

Features

🔐 Secure OAuth2 authentication with HaloPSA API
📊 Execute SQL queries against HaloPSA database
🔍 Intelligent schema search and query suggestions
📋 Complete database schema with 800+ tables
🤖 AI-friendly query building assistance
🌐 Full API exploration with swagger schema access
📖 Browse and search API endpoints with pagination
🔧 Direct API calls to any HaloPSA endpoint

Installation

NPM

Install the package from npm:

npm install -g @adamhancock/halopsa-mcp

Docker

Pull and run the Docker image:

docker run -e HALOPSA_URL=https://your-instance.halopsa.com \ -e HALOPSA_CLIENT_ID=your-client-id \ -e HALOPSA_CLIENT_SECRET=your-client-secret \ -e HALOPSA_TENANT=your-tenant \ ghcr.io/adamhancock/halopsa-mcp:latest

Usage with Claude Desktop

Using NPM Package

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{ "mcpServers": { "halopsa": { "command": "npx", "args": ["@adamhancock/halopsa-mcp"], "env": { "HALOPSA_URL": "https://your-instance.halopsa.com", "HALOPSA_CLIENT_ID": "your-client-id", "HALOPSA_CLIENT_SECRET": "your-client-secret", "HALOPSA_TENANT": "your-tenant" } } } }

Using Docker

Add to your Claude Desktop configuration:

{ "mcpServers": { "halopsa": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "HALOPSA_URL=https://your-instance.halopsa.com", "-e", "HALOPSA_CLIENT_ID=your-client-id", "-e", "HALOPSA_CLIENT_SECRET=your-client-secret", "-e", "HALOPSA_TENANT=your-tenant", "ghcr.io/adamhancock/halopsa-mcp:latest" ] } } }

Available Tools

Database Query Tools

`halopsa_list_tables`

List all available tables in the HaloPSA database:

{ filter: "fault" // Optional: filter tables by name }

`halopsa_list_columns`

List columns for a specific table:

{ tableName: "FAULTS", // Required: table name columnFilter: "email" // Optional: filter columns by name }

`halopsa_query`

Execute SQL queries against the HaloPSA database:

{ sql: "SELECT * FROM FAULTS WHERE Status = 1 LIMIT 10" }

`halopsa_table_info`

Get detailed information about a specific table including all columns, data types, and relationships:

{ tableName: "FAULTS" }

`halopsa_build_query`

Build SQL queries programmatically with a helper:

{ tableName: "FAULTS", columns: ["Faultid", "username", "Symptom"], // Optional: defaults to all columns conditions: { "Status": 1 }, // Optional: WHERE conditions orderBy: "datereported DESC", // Optional: ORDER BY clause limit: 10 // Optional: LIMIT clause }

API Exploration Tools

`halopsa_list_api_endpoints`

List all API endpoints with basic information. Supports pagination:

{ category: "Tickets", // Optional: filter by category limit: 100, // Optional: max results (default: 100) skip: 0 // Optional: skip for pagination }

`halopsa_get_api_endpoint_details`

Get complete details for specific API endpoints including parameters and schemas:

{ pathPattern: "ticket", // Required: pattern to match endpoints summaryOnly: false, // Optional: return only basic info includeSchemas: true, // Optional: include request/response schemas maxEndpoints: 10, // Optional: max endpoints to return includeExamples: false // Optional: include examples }

`halopsa_search_api_endpoints`

Search for API endpoints by keywords. Supports pagination:

{ query: "create ticket", // Required: search query limit: 50, // Optional: max results (default: 50) skip: 0 // Optional: skip for pagination }

`halopsa_get_api_schemas`

Get API schemas/models from the swagger definition. Supports pagination:

{ schemaPattern: "Ticket", // Optional: filter schemas by name limit: 50, // Optional: max schemas to return skip: 0, // Optional: skip for pagination listNames: false // Optional: include all matching schema names }

`halopsa_api_call`

Make authenticated API calls to any HaloPSA endpoint:

{ path: "/api/Ticket", // Required: API endpoint path method: "GET", // Optional: HTTP method (default: GET) body: {}, // Optional: request body for POST/PUT/PATCH queryParams: {} // Optional: URL query parameters }

Common Queries

Open Tickets

SELECT Faultid, username, Symptom, Status, datereported FROM FAULTS WHERE Status IN (1, 2, 3) ORDER BY datereported DESC

User List

SELECT uusername, uemail, usite, uextn FROM USERS WHERE uinactive = 0

Request Types

SELECT RTid as RequestTypeId, rtdesc as RequestTypeName FROM REQUESTTYPE WHERE RTVisible = 1

Development

Run in Development Mode

pnpm run dev

Test Connection

node dist/index.js

Schema Information

The MCP includes a complete HaloPSA database schema with:

818 tables
Key tables include:
- FAULTS (622 columns) - Tickets/Requests
- USERS (213 columns) - User information
- SITE (115 columns) - Client/Site data
- ACTIONS (196 columns) - Ticket actions
- REQUESTTYPE (332 columns) - Ticket types

Security Notes

Never commit .env files
Store credentials securely
Use read-only API credentials when possible
Rotate API keys regularly

License

ISC

HaloPSA MCP Server

HaloPSA MCP Server

Features

Installation

NPM

Docker

Usage with Claude Desktop

Using NPM Package

Using Docker

Available Tools

Database Query Tools

`halopsa_list_tables`

`halopsa_list_columns`

`halopsa_query`

`halopsa_table_info`

`halopsa_build_query`

API Exploration Tools

`halopsa_list_api_endpoints`

`halopsa_get_api_endpoint_details`

`halopsa_search_api_endpoints`

`halopsa_get_api_schemas`

`halopsa_api_call`

Common Queries

Open Tickets

User List

Request Types

Development

Run in Development Mode

Test Connection

Schema Information

Security Notes

License

Related Resources

Tools

New MCP Servers

MCP directory API