@goxtechnologies/connectwise-psa-mcp

MCP server connecting AI assistants to ConnectWise PSA (Manage) — 22 tools, 509 named operations, timesheet approval workflow, and MSP analytics. Built for MSP technicians experimenting with AI-assisted workflows.

Query tickets, companies, contacts, agreements, time entries, projects, and more. Tool and operation counts are read from the build at runtime — see cw_list_operations or the startup banner for live numbers.

This project started as a personal experiment — I wanted to see how far I could push AI assistants as a daily driver for MSP operations. It grew from a simple API wrapper into a full-featured toolkit with timesheet validation, analytics dashboards, and smart dispatching.

Built for MSP technicians and IT professionals who like to tinker. If you're running ConnectWise and want to experiment with AI-assisted workflows — querying your PSA through natural language, automating reports, validating timesheets — this gives you the plumbing to do it.

Heads up: This is an active experiment. The core tools (API calls, ticket queries, time entry validation) are well-tested and used daily. Many of the analytics handlers and advanced features, however, have seen limited real-world testing. Things may not work perfectly in every environment. Contributions, bug reports, and feedback are welcome.

Quick Start

1. Install

npm install -g @goxtechnologies/connectwise-psa-mcp

2. Configure credentials

Create ~/.config/connectwise-psa/.env:

CW_API_URL=https://na.myconnectwise.net/v4_6_release/apis/3.0
CW_COMPANY_ID=yourcompany
CW_PUBLIC_KEY=yourpublickey
CW_PRIVATE_KEY=yourprivatekey
CW_AUTH_PREFIX=yourcompany+
CW_TIMEZONE=America/Toronto

CW_AUTH_PREFIX is your company ID followed by +, matching what ConnectWise expects in the Basic auth username.

CW_TIMEZONE is an IANA timezone name used when displaying dates in analytics and timesheet reports. The default is UTC. Dates sent to the ConnectWise API always remain in UTC — this setting affects display only.

3. Verify

connectwise-psa-mcp

The server writes its startup message to stderr. If credentials are missing, it still registers all tools — calls to those tools return a descriptive error until credentials are set.

Features

25 MCP Tools

Tools are organized into 9 groups:

| Group | Tools | What they do | |-------|-------|--------------| | Discovery | cw_search_endpoints, cw_endpoint_details, cw_api_categories, cw_category_endpoints | Browse and inspect the full ConnectWise API catalogue from a bundled SQLite database | | Execution | cw_api_call, cw_raw_request | Execute API calls with full GET response. Non-GET requires confirm=true; gated by CW_RAW_WRITES_ENABLED | | Pagination | cw_paginated_fetch, cw_count | Auto-paginate collections (250 items/page, hard cap 5000) or fetch record counts instantly | | Memory | cw_save_query, cw_list_queries, cw_delete_query, cw_clear_queries | Persist frequently-used queries across sessions with usage-count tracking | | Composite | cw_ticket_context, cw_member_dashboard, cw_agreement_health, cw_audit_ticket | Fan out multiple parallel API calls and return a single assembled result | | Batch | cw_batch_update | Execute multiple PATCH/POST/DELETE operations sequentially, with a mandatory dry-run preview before any data is changed | | Validation | cw_validate_timesheets, cw_accrual_balance, cw_approve_timesheets | Validate time entries against 9 business rules (rounding, overlaps, notes, overtime, accruals, etc.) and run a full approval workflow | | Named Operations | cw_operation, cw_list_operations | Execute or browse the pre-built operations registry by name | | Reports | cw_report, cw_list_reports, cw_discover_report, cw_report_purge | Fetch CW web reports via Playwright, list available reports, scaffold new report definitions, and purge cached history |

Named Operations Registry

Pre-built operations covering the active ConnectWise Manage API surface. The exact count is read from the built registry at runtime — see the startup banner (stderr) or call cw_list_operations with no parameters.

Write safety: read-only queries (GET) require no confirmation; write operations (POST, PATCH, DELETE) require params.confirm: true. Without it, cw_operation returns a dry-run preview showing the exact method, path, conditions, and body that would be sent — no data is modified.

Use cw_list_operations to browse by category or keyword. Use cw_operation to execute by name:

cw_operation: list_open_tickets
cw_operation: get_ticket { id: 12345 }
cw_operation: update_ticket { id: 12345, body: "{\"status\":{\"id\":7}}", confirm: true }
cw_operation: company_360_view { company_id: 42 }

Operation categories include: Tickets, Companies, Contacts, Agreements, Time, Projects, Procurement, Scheduling, Sales, and MSP Analytics.

Analytics Handlers

The MSP Analytics category contains server-side aggregation handlers that assemble higher-level views from multiple API calls. These cover:

• Time totals and utilization by member
• SLA compliance and first-response time
• Contract profitability and agreement renewals
• Client health scorecards and at-risk client detection
• Team leaderboards and dispatch efficiency
• Project budget burn and phase completion
• Pipeline value and opportunity win rates
• Procurement spend and expense approvals
• Asset aging, warranty expiration, and license compliance

Coverage audit

Run npm run audit:coverage to compare the registry against the bundled OpenAPI spec (data/manage.json) — emits unique-endpoint coverage %, per-method counts, and flags any registry entry that doesn't match a spec path.

Configuration

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CW_API_URL | Yes | Full base URL including version path, e.g. https://na.myconnectwise.net/v4_6_release/apis/3.0 | | CW_COMPANY_ID | Yes | Your ConnectWise company identifier | | CW_PUBLIC_KEY | Yes | API member public key | | CW_PRIVATE_KEY | Yes | API member private key | | CW_AUTH_PREFIX | Yes | Company ID followed by +, e.g. yourcompany+ | | CW_TIMEZONE | No | IANA timezone name for date display in analytics and timesheet reports. Default: UTC. Example: America/Toronto. The API always operates in UTC; this setting converts displayed dates only. | | CW_RAW_WRITES_ENABLED | No | Set to false/0/no to disable non-GET verbs in cw_api_call / cw_raw_request. Defaults to enabled; non-GET still requires confirm=true even when enabled. Use false on shared/hosted deployments that should never write via the raw tools. | | CW_DISCOVER_ALLOW_OFFORIGIN | No | Set to true to let cw_discover_report navigate URLs outside the ConnectWise origin. Defaults to rejecting off-origin targets to prevent authenticated-browser exfiltration via prompt injection. | | CW_DATA_DIR | No | Override the user-data directory (SQLite DBs, browser state, downloads). Defaults to ~/.config/connectwise-psa/data/. Useful for containers and CI. | | CW_WEB_VERSION | No | Overrides the default CW web build string used by URL-strategy reports. Defaults to v2026_1. Bump when CW ships a new web build rather than waiting for a package release. | | CW_ENV_PERMISSIVE | No | Set to true to load a .env file even when its permissions are group- or world-readable. Not recommended; intended only for non-production experiments. |

Persisted state

The server writes runtime state under ~/.config/connectwise-psa/data/ (override with CW_DATA_DIR):

| File | Purpose | Sensitive? | |------|---------|------------| | fast-memory.db | Saved queries for cw_save_query/cw_list_queries | Contains bodies of saved requests | | report-cache.db | Cached web reports + history + calibration | Yes — contains full report data | | browser-state.json | Playwright storageState (cookies, localStorage) | Yes — mode 0600 | | browser-downloads/ | Temporary files exported by web reports | Yes — swept on startup |

Use cw_report_purge to prune the report-cache.db history table. Upgrading from <=1.7.x auto-migrates DBs from the old in-package location on first run.

.env File Location

The server searches for credentials in this order:

1. ~/.config/connectwise-psa/.env — primary location, always writable
2. <package_root>/.env — legacy fallback

Existing environment variables always take precedence over .env file values.

Regional API URLs

| Region | URL pattern | |--------|-------------| | North America | https://na.myconnectwise.net/v4_6_release/apis/3.0 | | Australia/NZ | https://au.myconnectwise.net/v4_6_release/apis/3.0 | | Europe | https://eu.myconnectwise.net/v4_6_release/apis/3.0 | | UK | https://uk.myconnectwise.net/v4_6_release/apis/3.0 |

Confirm your exact URL in ConnectWise Manage under System > Setup Tables > API Keys.

Data files

The data/ directory holds the API catalogue powering the discovery tools (cw_search_endpoints, cw_endpoint_details, cw_api_categories, cw_category_endpoints).

| File | Role | Tracked in git? | Shipped on npm? | |------|------|-----------------|-----------------| | manage.json | Source — ConnectWise Manage OpenAPI spec | Yes (source of truth) | No | | connectwise_api.db | Build artifact — SQLite index over the spec (3,053 endpoints, 19,665 parameters) | No (gitignored) | Yes (rebuilt by prepublishOnly) | | reports.json | Web report definitions | Yes | Yes |

Why the DB is gitignored: it's a derived artifact. Each rebuild changes the 2 MB binary, which would bloat git history for no benefit. npm install && npm run build && npm run build:db regenerates it from manage.json in under 10 seconds. Users installing via npx or the .dxt bundle get the prebuilt DB inside the tarball (CI rebuilds it before every publish).

Companion sibling MCPs follow the same pattern. The RMM MCP (@goxtechnologies/connectwise-rmm-mcp) gitignores its connectwise_rmm_api.db the same way. The CPQ MCP (@goxtechnologies/connectwise-cpq-mcp) has no DB at all — its 29 endpoints are hand-coded in src/utils/endpoints.ts because SQLite indexing is overkill at that scale.

No sensitive data. The DB contains public ConnectWise API metadata only: paths, methods, parameter names, response schemas. No credentials, no tenant data, no customer info.

Usage with Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "connectwise-psa": {
      "command": "connectwise-psa-mcp",
      "env": {
        "CW_API_URL": "https://na.myconnectwise.net/v4_6_release/apis/3.0",
        "CW_COMPANY_ID": "your-id",
        "CW_PUBLIC_KEY": "your-key",
        "CW_PRIVATE_KEY": "your-key",
        "CW_AUTH_PREFIX": "your-prefix+",
        "CW_TIMEZONE": "America/Toronto"
      }
    }
  }
}

The config file is located at:

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

Restart Claude Desktop after saving.

Usage with Claude Code

Register the MCP server with Claude Code:

claude mcp add connectwise-psa -- connectwise-psa-mcp

Then ensure your credentials are set in ~/.config/connectwise-psa/.env.

Usage Standalone (npx)

Run without a global install:

CW_API_URL=https://na.myconnectwise.net/v4_6_release/apis/3.0 \
CW_COMPANY_ID=yourcompany \
CW_PUBLIC_KEY=yourpublickey \
CW_PRIVATE_KEY=yourprivatekey \
CW_AUTH_PREFIX=yourcompany+ \
npx @goxtechnologies/connectwise-psa-mcp

Or rely on the .env file at ~/.config/connectwise-psa/.env and run:

npx @goxtechnologies/connectwise-psa-mcp

Requirements

• Node.js 18 or later

Releasing

Releases are automated. Bump version in both package.json and manifest.json (they must match), commit, then push a matching tag:

git tag v1.8.1
git push origin v1.8.1

The Release workflow builds, runs tests, verifies the tag matches both version fields, publishes to npm via OIDC Trusted Publishing (with provenance), builds the Claude Desktop .dxt bundle, and attaches it to an auto-generated GitHub Release.

Pull requests and pushes to main run the CI workflow (build + unit tests).

Acknowledgments

Prior public work in this space: jasondsmith72/CWM-API-Gateway-MCP.

License and Legal Notices

MIT Licensed

@goxtechnologies/connectwise-psa-mcp is released under the MIT License. See the LICENSE file for the full text.

Source code: github.com/jencryzthers/connectwise-psa-mcp.

Experimental Software

This software is an active experiment in AI-assisted MSP operations. The core tools (API calls, ticket queries, time entry validation) are well-tested and used daily. Many of the analytics handlers and advanced features, however, have seen limited real-world testing. Features may be added, changed, or removed without notice between versions.

This software is NOT a substitute for professional judgment. All outputs, recommendations, and actions should be independently verified by qualified IT professionals before being relied upon.

When used with an AI assistant (Claude, GPT, or similar), the AI may propose or execute actions that are incorrect, incomplete, or destructive. Human review of all AI-proposed actions is strongly recommended.

ConnectWise Trademark Notice

"ConnectWise," "ConnectWise PSA," and "ConnectWise Manage" are trademarks or registered trademarks of ConnectWise, LLC.

This package is NOT an official ConnectWise product. It is NOT developed, endorsed, sponsored, certified, or approved by ConnectWise, LLC. GOX Technologies Inc. has no affiliation with ConnectWise, LLC. These marks are referenced solely to identify the third-party APIs this software interoperates with.

ConnectWise API Requirements

To use this software you must hold your own valid ConnectWise PSA (Manage) license and API credentials. Your use of the ConnectWise APIs is governed by your agreements with ConnectWise, LLC. GOX Technologies Inc. is not responsible for any ConnectWise Terms of Service violations that result from your use of this software.

Data and Security

• GOX Technologies Inc. has no access to your API credentials, your ConnectWise data, or any actions performed through this software.
• This software can create, modify, and delete records in your ConnectWise PSA instance, approve timesheets, and modify financial data. You bear full responsibility for every action performed through this software, including actions initiated by AI assistants using this software as an MCP integration.
• Store your API credentials securely. Use minimum-privilege API keys.
• If using this software with an AI assistant, validate every proposed action before it executes. AI systems can produce incorrect or destructive outputs.

No Warranty / Limitation of Liability

THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. GOX TECHNOLOGIES INC. IS NOT LIABLE FOR ANY DATA LOSS, SERVICE DISRUPTION, UNAUTHORIZED ACCESS, FINANCIAL LOSS, OR ANY OTHER DAMAGE ARISING FROM YOUR USE OF THIS SOFTWARE. USE AT YOUR OWN RISK.

See the LICENSE file for the complete MIT terms.

Third-Party Dependencies

This software uses open-source packages governed by their own licenses:

• better-sqlite3 -- MIT License
• @modelcontextprotocol/sdk -- MIT License

Copyright (c) 2024-2026 GOX Technologies Inc. Released under the MIT License.

Source and issues: github.com/jencryzthers/connectwise-psa-mcp