@teamnetwork-nz/vsa-mcp-server

MCP server for Kaseya VSA 9.5 — remote monitoring and management (RMM) via the VSA REST API.

Compatible with Claude Desktop, Claude Code, Cursor, Cline, and any MCP-capable client.

Requirements

• Node.js 20+
• Kaseya VSA 9.5 instance with REST API access
• VSA personal token (VSA → User menu → Personal Tokens)

Installation

npx @teamnetwork-nz/vsa-mcp-server

Or install globally:

npm install -g @teamnetwork-nz/vsa-mcp-server
vsa-mcp-server

Configuration

Set these environment variables before starting the server:

Required

| Variable | Description | |---|---| | VSA_BASE_URL | Base URL of your VSA instance, e.g. https://vsa.example.com | | VSA_USERNAME | VSA username | | VSA_PERSONAL_TOKEN | Personal token from VSA → User menu → Personal Tokens |

Optional

| Variable | Default | Description | |---|---|---| | VSA_READWRITE | false | Set to true to enable write operations | | VSA_DATETIMEFORMAT | local | Timezone for date input/output — see Datetime handling |

Datetime handling

All VSA API timestamps are UTC. By default this server converts them automatically — inputs from local time to UTC (in OData filter expressions), outputs from UTC to local — so you never have to think about UTC offsets.

VSA_DATETIMEFORMAT controls which timezone is applied:

| Value | Behaviour | |---|---| | local (default) | Use the system's local timezone (Intl.DateTimeFormat auto-detection) | | IANA name e.g. Pacific/Auckland | Use this explicit timezone regardless of system locale | | UTC | No conversion — dates pass through unchanged |

Output dates are returned as strings with a short timezone name, e.g. 2026-05-09 13:44:56 NZST.

OData filter dates should be written as local wall-clock time using the OData datetime literal format: datetime'2024-01-15T09:00:00'. The server converts them to UTC before sending to the API.

Claude Desktop configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "vsa": {
      "command": "npx",
      "args": ["-y", "@teamnetwork-nz/vsa-mcp-server"],
      "env": {
        "VSA_BASE_URL": "https://vsa.example.com",
        "VSA_USERNAME": "your-username",
        "VSA_PERSONAL_TOKEN": "your-token"
      }
    }
  }
}

Claude Code configuration

claude mcp add vsa \
  -e VSA_BASE_URL=https://vsa.example.com \
  -e VSA_USERNAME=your-username \
  -e VSA_PERSONAL_TOKEN=your-token \
  -- npx -y @teamnetwork-nz/vsa-mcp-server

Available tools

Connection & authentication

| Tool | Description | |---|---| | vsa_test_connection | Test connectivity and verify credentials |

Organisations

| Tool | Description | |---|---| | vsa_list_orgs | List all organisations (clients) with OrgId, OrgRef, contact info | | vsa_get_org | Get full details for a specific organisation |

Agents

| Tool | Description | |---|---| | vsa_list_agents | List managed agents — filter by org, name, IP, or OData expression | | vsa_get_agent | Get full details for a specific agent by ID |

Assets & audit

| Tool | Description | |---|---| | vsa_list_assets | List asset records with hardware/OS details | | vsa_get_asset | Get full asset details for a specific asset ID | | vsa_get_asset_custom_fields | Get custom field values for an asset | | vsa_get_audit_summary | Hardware/OS/disk summary across agents — filter by org or agent | | vsa_run_audit | Trigger an audit on a specific agent immediately | | vsa_get_disk_volumes | Disk volume details (size, free space, drive letter) across all agents | | vsa_get_local_groups | Local user groups on a specific agent |

Procedures

| Tool | Description | |---|---| | vsa_list_procedures | List available agent procedures (automation scripts) | | vsa_run_procedure | Execute a procedure on a specific agent (runs asynchronously) | | vsa_get_procedure_history | Get execution history for a procedure |

Variables

| Tool | Description | |---|---| | vsa_list_agent_variables | List agent variable definitions | | vsa_set_agent_variable | Set a variable value on a specific agent |

Agent guidance

Organisation hierarchy

VSA organises agents into organisations and machine groups. The OrgRef from vsa_list_orgs (e.g. acme-81234) forms the MachineGroup path: root.<OrgRef>. Use this as the orgName parameter in vsa_list_agents.

OData filtering

All list tools support OData $filter, $orderby, $top, and $skip:

# Agents matching "server" in ComputerName
filter: substringof('server', ComputerName) eq true

# Agents in a specific org (use M suffix for Edm.Decimal OrgId)
filter: OrgId eq 42M

# Offline agents
filter: Online eq 0

Procedure execution

vsa_run_procedure dispatches the procedure asynchronously — the agent may not run it immediately. Use vsa_get_procedure_history to check the result after a short wait.

Read-only mode (default)

All write operations require VSA_READWRITE=true. In read-only mode, tools like vsa_run_procedure and vsa_run_audit are still registered (they are operational tools, not configuration writes) — but broader configuration changes require the flag.

Development

npm install
npm run build

# Run locally
VSA_BASE_URL=https://vsa.example.com \
VSA_USERNAME=your-username \
VSA_PERSONAL_TOKEN=your-token \
node dist/index.js

Test with the MCP inspector:

npx @modelcontextprotocol/inspector node dist/index.js

License

MIT