ConnectWise PSA

mcp-connectwise-psa

An MCP (Model Context Protocol) server for ConnectWise PSA (Manage) — curated tools across 8 toolsets covering technicians, dispatchers, and billing, plus an escape hatch for the rest of the API and a read-only SQL toolset for on-prem deployments, so an AI assistant works PSA the way each role does:

• Tickets — search / my tickets / full detail with notes, create, update status/priority/owner, add discussion/internal notes, plus board·status·priority discovery and per-ticket time & tasks. Covers **service *and* project tickets** — ConnectWise keeps them on separate resources, so the read tools query both and the by-id tools detect which one an id belongs to
• Time — log time against tickets (with work role, work type and CW's Deduct for breaks), review your own time, work-role and work-type lookup, and list & submit your timesheets
• Companies & contacts — fast lookup, contact detail (phones/emails), company sites
• Configurations — devices/assets with serials, IPs, OS, warranty (read-only)
• Dispatch *(schedule)* — schedule entries (list/mine/create/reschedule/cancel), and members with their timezone, working hours, and free-vs-booked availability
• Invoicing *(finance, read-only)* — invoices, agreements, and unbilled billable time ready to bill
• SQL *(on-prem only)* — read-only T-SQL straight against the cwwebapp_* Manage database for the cross-table reporting REST cannot express, with a searchable schema catalog and a library of saved queries the assistant can grow. Enabled by configuring CW_DB_*; where it is, every session that does not narrow its toolsets has it
• Toolsets & personas — enable only what a session needs via the x-cw-toolsets header (or CW_TOOLSETS); presets tech / dispatch / invoicing / all. Default is all — narrow it per session when a smaller surface is wanted. Each tool also reports its toolset as _meta.group, so an aggregator (the MSPStack gateway) can group and switch tools by capability
• Per-member API keys (BYOK) — each user supplies their own ConnectWise member keys; ConnectWise enforces that member's security role, and every write is attributed to the *actual person*
• Transports — stdio for local use, streamable HTTP for shared deployments; Docker image included

Quick start (local, stdio)

npm install && npm run build

CW_SITE=na.myconnectwise.net \ CW_COMPANY_ID=yourcompany \ CW_CLIENT_ID= \ CW_PUBLIC_KEY=xxxx CW_PRIVATE_KEY=yyyy \ CW_MEMBER_IDENTIFIER=jdoe \ node dist/index.js

Claude Desktop / Claude Code config:

{

"mcpServers": { "connectwise": { "command": "node", "args": ["/path/to/mcp-connectwise-psa/dist/index.js"], "env": { "CW_SITE": "na.myconnectwise.net", "CW_COMPANY_ID": "yourcompany", "CW_CLIENT_ID": " ", "CW_PUBLIC_KEY": "xxxx", "CW_PRIVATE_KEY": "yyyy", "CW_MEMBER_IDENTIFIER": "jdoe" } } } }

A clientId is required by the ConnectWise API — register a (free) integration at developer.connectwise.com. API member keys are created in ConnectWise under My Account → API Keys (per member) or System → Members → API Members (integration accounts).

HTTP deployment

CW_SITE=… CW_COMPANY_ID=… CW_CLIENT_ID=… \

node dist/index.js --transport http --port 3000

Or with Docker: docker build -t mcp-connectwise-psa . && docker run -p 3000:3000 -e CW_SITE -e CW_COMPANY_ID -e CW_CLIENT_ID mcp-connectwise-psa

Sessions are held in memory — run a single instance (or sticky sessions).

Access control — bring your own keys (BYOK)

Over HTTP there is no MCP-level role system. Each session presents its own ConnectWise member API keys, and ConnectWise itself is the access control: the member's security role decides what succeeds, and every note and time entry is attributed to that member.

Send your keys on the initialize request (and on every subsequent request in the session):

x-cw-public-key:  <public key>

x-cw-private-key: x-cw-member-id: (optional — enables "my tickets"/"my time")

• A request with no keys is rejected with 401; both key headers are required together.
• Keys are never logged. A session is bound to a SHA-256 hash of the key pair; presenting a different pair on the same session id → 403.
• Create member API keys in ConnectWise under My Account → API Keys. Each tech uses their own.

Local stdio is single-user and uses the CW_PUBLIC_KEY/CW_PRIVATE_KEY from the environment instead of headers.

Toolsets

Tools are grouped into toolsets so a session only sees the capabilities it needs — a dispatcher doesn't need the invoicing tools, and a small tool surface keeps the assistant focused (and its context cheap). Whether a write actually succeeds is still governed by the member's ConnectWise security role.

Presets bundle keys per persona: tech = tickets + time + companies + configurations · dispatch = tickets + schedule + companies + configurations · invoicing = finance + time + companies · all = every key. The persona presets deliberately exclude sql — a technician surface is not a database surface.

The `advanced` toolset is the escape hatch (in all, but in no persona preset): cw_find_endpoint searches a bundled catalog of the whole ConnectWise API, and cw_get performs a read-only GET on any path — so an assistant can reach the long tail (procurement, sales, projects, system…) the curated tools don't wrap. To drop it, name the keys or a persona preset instead (x-cw-toolsets: tech).

Select toolsets with a comma list mixing keys and presets:

• HTTP — the x-cw-toolsets header, per session: x-cw-toolsets: dispatch or x-cw-toolsets: tech,finance.
• stdio — the CW_TOOLSETS env var or --toolsets flag: CW_TOOLSETS=invoicing.

The default is the `all` preset — every capability the server is configured for; a client that wants a smaller surface names the keys or persona it needs. Unknown keys in CW_TOOLSETS/--toolsets fail fast; unknown tokens in the x-cw-toolsets header are ignored. The only destructive tool is cw_delete_schedule_entry (dispatch); finance is read-only. cw_db_save_query writes, but to the query-library file — database access itself is SELECT-only by grant.

Exception: the sql toolset

Every other toolset runs on the caller's own ConnectWise keys, so ConnectWise filters what comes back. sql does not: it reads the database through a server-wide read-only login, so its results are not attributed to a member and are not filtered by that member's security role, board restrictions or record permissions.

Configuring CW_DB_* is therefore the decision that matters. Once a server has a database, sql is an ordinary key: it is in all, it is in the default selection, and every session that does not narrow its toolsets can read the whole PSA database. A server without CW_DB_* prunes it silently, so nothing breaks for deployments that never wanted it.

If you need database access for some callers but not others, do it per session (x-cw-toolsets: tech) or in front of the server — an aggregating gateway can tier the cw_db_* tools separately. What bounds the damage on the server side is the login: see the runbook below, and keep it to db_datareader with credential columns denied.

SQL toolset (on-prem database)

Cloud-hosted ConnectWise gives you no database access, so this toolset is for on-prem deployments only. Point it at the Manage database with a login created for exactly this purpose:

CW_DB_HOST=sqlhost CW_DB_NAME=cwwebapp_acme \

CW_DB_USER=cw_mcp_ro CW_DB_PASSWORD=… \ CW_DB_QUERY_LIBRARY=/data/cw-queries.json \ node dist/index.js

That is all it takes: with a database configured the sql toolset is part of the default selection. Naming sql without CW_DB_* fails at startup (a selection that only *includes* it, like all, is pruned instead). Nothing connects to the database until a session actually uses a tool.

Start from the reporting views. ConnectWise ships denormalized v_rpt_* views that already join board, status, company and contact onto a record — v_rpt_service, v_rpt_time, v_rpt_company, v_rpt_invoices, v_rpt_agreementlist. cw_db_find_table knows them and the base tables behind them; it carries key columns only, because the exact column list is one INFORMATION_SCHEMA query away and is always right for *your* version.

The saved-query library is the committed core plus a writable overlay at CW_DB_QUERY_LIBRARY (JSON, { version, queries[] }). Overlay entries win by slug, cw_db_save_query appends to it, and scripts/import-queries.mjs fills it from an existing BrightGauge export:

node scripts/import-queries.mjs /path/to/brightgauge-export

Imported queries stay outside this repository — they are your reporting and can carry company names and rates. On a container, point CW_DB_QUERY_LIBRARY at mounted storage or saved queries die with the container.

The login is the security boundary

There is no statement validation: the server sends the model's SQL to SQL Server as written, so what the login is allowed to do is exactly what can happen. Two scripts set it up and prove it.

Create it — edit the four variables at the top, run as sysadmin. @WhatIf defaults to 1, so the first run only prints the plan:

sqlcmd -S SQLHOST\CWPROD -d master -i scripts/create-readonly-login.sql

It creates the login in no server role, adds it to db_datareader in one database, DENYs everything else (EXECUTE, all writes, DDL, BACKUP), and DENYs SELECT on every credential-looking column it *discovers* — the names move between Manage versions and every MSP adds its own, so they are found rather than hard-coded. Re-running is safe and is how you re-apply the DENYs after an upgrade adds tables. It reports the instance-wide settings that must be off but never changes them: disabling xp_cmdshell can break other applications, so that stays a decision.

Verify it — as the new login, not as an admin:

sqlcmd -S SQLHOST\CWPROD -d cwwebapp_acme -U cw_mcp_ro -P '<password>' -i scripts/verify-readonly-login.sql

Every check prints PASS or FAIL: SELECT works, UPDATE/CREATE TABLE are refused (inside a transaction that always