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