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=<integration clientId> \
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": "<clientId>",
"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
| Route | Purpose |
|---|
POST/GET/DELETE /mcp | MCP streamable-http endpoint |
GET /health | Liveness probe |
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: <private key>
x-cw-member-id: <your member identifier> (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.
| Toolset key | Tools |
|---|
tickets | cw_search_tickets, cw_my_tickets, cw_get_ticket, cw_create_ticket, cw_update_ticket, cw_add_ticket_note, cw_bundle_tickets, cw_list_boards, cw_get_board, cw_list_priorities, cw_list_ticket_time, cw_list_ticket_tasks |
time | cw_create_time_entry, cw_update_time_entry, cw_list_my_time, cw_list_work_roles, cw_list_work_types, cw_list_my_timesheets, cw_submit_timesheet |
companies | cw_search_companies, cw_get_company, cw_search_contacts, cw_get_contact, cw_list_company_sites |
configurations | cw_list_configurations, cw_get_configuration |
schedule | cw_list_schedule_entries, cw_my_schedule, cw_schedule_ticket, cw_update_schedule_entry, cw_delete_schedule_entry, cw_member_availability, cw_list_members, cw_get_member |
finance | cw_list_invoices, cw_get_invoice, cw_list_agreements, cw_get_agreement, cw_list_unbilled_time |
advanced | cw_find_endpoint (search the full CW API — ~1,150 endpoints), cw_get (read-only GET on any path) |
sql (on-prem, needs CW_DB_*) | cw_db_query (read-only T-SQL), cw_db_find_table (schema catalog), cw_db_find_query / cw_db_save_query (saved-query library) |
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.