superfast-halopsa-mcp

An MCP (Model Context Protocol) server that gives AI assistants like Claude access to your HaloPSA instance — its reporting database and its full REST API. Run it with npx; no cloning or building required.

What it does

Once connected, the assistant can explore and query HaloPSA on your behalf:

• 🔐 OAuth2 client-credentials auth against the HaloPSA API
• 📊 Run SQL against the HaloPSA reporting database (halopsa_query)
• 🧭 Discover the schema — list tables, list columns, inspect a table (halopsa_list_tables, halopsa_list_columns, halopsa_table_info)
• 🧱 Build queries without writing raw SQL (halopsa_build_query)
• 🌐 Explore the REST API from the bundled Swagger definition — list, search and inspect endpoints and schemas (halopsa_list_api_endpoints, halopsa_search_api_endpoints, halopsa_get_api_endpoint_details, halopsa_get_api_schemas)
• 🔧 Call any REST endpoint directly, including endpoints that require a top-level JSON array body such as POST /api/Actions (halopsa_api_call)

Requirements

• Node.js 20 or newer
• A HaloPSA API application (Client ID + Secret) scoped for the access you want the assistant to have. See Credentials & security below.

Configuration

The server is configured entirely through environment variables:

| Variable | Required | Description | | ----------------------- | -------- | ----------------------------------------------------------------- | | HALOPSA_URL | yes | Base URL of your HaloPSA instance, e.g. https://psa.example.com | | HALOPSA_CLIENT_ID | yes | OAuth2 client ID of your HaloPSA API application | | HALOPSA_CLIENT_SECRET | yes | OAuth2 client secret | | HALOPSA_TENANT | yes | HaloPSA tenant name (e.g. Production) |

There's a template in .env.example.

Setup

Claude Desktop

Edit your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server under mcpServers:

{
  "mcpServers": {
    "halopsa": {
      "command": "npx",
      "args": ["-y", "superfast-halopsa-mcp"],
      "env": {
        "HALOPSA_URL": "https://psa.example.com",
        "HALOPSA_CLIENT_ID": "your-client-id",
        "HALOPSA_CLIENT_SECRET": "your-client-secret",
        "HALOPSA_TENANT": "Production"
      }
    }
  }
}

Then fully quit and reopen Claude Desktop.

Claude Code (CLI)

claude mcp add halopsa \
  --env HALOPSA_URL=https://psa.example.com \
  --env HALOPSA_CLIENT_ID=your-client-id \
  --env HALOPSA_CLIENT_SECRET=your-client-secret \
  --env HALOPSA_TENANT=Production \
  -- npx -y superfast-halopsa-mcp

Let Claude set it up for you

Paste this into Claude Desktop or Claude Code, filling in your four values first:

Please add an MCP server called halopsa to my configuration. It runs via npx -y superfast-halopsa-mcp and needs these environment variables: HALOPSA_URL=https://psa.example.com, HALOPSA_CLIENT_ID=<my client id>, HALOPSA_CLIENT_SECRET=<my client secret>, HALOPSA_TENANT=Production. On Claude Desktop, edit claude_desktop_config.json and add it under mcpServers; on Claude Code, run the equivalent claude mcp add command. Then tell me to restart.

Available tools

| Tool | Purpose | | ---- | ------- | | halopsa_list_tables | List reporting-database tables (optionally filtered) | | halopsa_list_columns | List columns for a table | | halopsa_table_info | Inspect a table's columns, types and likely relationships | | halopsa_query | Execute SQL against the reporting database | | halopsa_build_query | Build a SELECT query from parts (no raw SQL) | | halopsa_list_api_endpoints | Browse REST endpoints (paginated) | | halopsa_search_api_endpoints | Search REST endpoints by keyword | | halopsa_get_api_endpoint_details | Full details/schemas for matching endpoints | | halopsa_get_api_schemas | Swagger request/response models | | halopsa_api_call | Authenticated call to any endpoint (object or array body) |

Credentials & security

• The Client ID/Secret you supply grant the assistant whatever that HaloPSA API application is scoped for. Scope the application to the least privilege you need (ideally read-only for reporting/analytics use) rather than reusing an admin application.
• Never commit real credentials. Keep them in your MCP client config or a local .env (git-ignored) — not in source control.
• If several people share one API application, they all act as that single identity in HaloPSA and can see everything it can see. Prefer a dedicated, low-privilege application for shared use.

Running from source

git clone https://github.com/jamescash1976/halopsa-mcp.git
cd halopsa-mcp
npm install          # runs the build automatically via "prepare"
cp .env.example .env # then fill in your values
npm run dev          # watch mode with tsx

Credits & licence

This package is a maintained fork of @adamhancock/halopsa-mcp by Adam Hancock, republished under a new name with bug fixes (JSON-array request bodies and an ESM swagger.json import fix) by James Cash / Superfast IT.

Licensed under the ISC License — see LICENSE. Original copyright remains with Adam Hancock; modifications © James Cash.