connectwise-manage-mcp

ConnectWise Manage MCP Server

Let your AI assistant work directly with ConnectWise Manage. Search tickets, log time, look up companies and contacts, manage projects — through natural conversation instead of clicking through the CWM interface.

This is a Model Context Protocol (MCP) server that gives Claude (or any MCP-compatible AI) 83 tools covering the daily operations ConnectWise Manage shops depend on. Works with both cloud-hosted and self-hosted CWM instances — just point it at your server.

Part of the MSP Claude Plugins ecosystem — a growing suite of AI integrations for the MSP stack including Autotask, Datto RMM, IT Glue, HaloPSA, NinjaOne, Huntress, and more. Built by MSPs, for MSPs.

One-Click Deployment

Note on registry auth: This server depends only on public npm packages, so the Cloudflare and DigitalOcean cloud builders install its dependencies anonymously — no token is required for one-click deploy. (If a future release adds a private @wyre-ai/* dependency, you would supply a GitHub PAT with read:packages as a build variable — NODE_AUTH_TOKEN for Cloudflare Workers, a build-time GITHUB_TOKEN secret for DigitalOcean.)

Installing the published package: The released package is published to the GitHub Packages npm registry, which requires authentication on every install (even for public packages). To install it, authenticate npm to npm.pkg.github.com with a GitHub PAT that has read:packages:

export NODE_AUTH_TOKEN=$(gh auth token)
npm install @wyre-ai/connectwise-manage-mcp

For deploying to Azure Container Apps with Entra ID OAuth 2.1, see AZURE_ACA_DEPLOYMENT.md.

Configuration

Environment Variables

Variable	Required	Description
CW_MANAGE_COMPANY_ID	For stdio and AUTH_MODE=env	Your ConnectWise company identifier
CW_MANAGE_PUBLIC_KEY	For stdio and AUTH_MODE=env	API member public key
CW_MANAGE_PRIVATE_KEY	For stdio and AUTH_MODE=env	API member private key
CW_MANAGE_CLIENT_ID	For stdio and AUTH_MODE=env	Client ID from ConnectWise Developer Portal
CW_MANAGE_URL	No	API base URL (see below)
CW_MANAGE_REJECT_UNAUTHORIZED	No	Set to false for self-signed certs (default: true)
MCP_TRANSPORT	No	stdio (default) or http
MCP_HTTP_PORT	No	HTTP port (default: 8080)
MCP_HTTP_HOST	No	Bind address when MCP_TRANSPORT=http. Defaults to 127.0.0.1. A configured CONDUIT_S2S_SECRET honors this value. The container image sets 0.0.0.0.
CONDUIT_S2S_SECRET	Yes for HTTP	Service-to-service secret. The HTTP server logs an error and exits non-zero when this is empty or a known placeholder (changeme, secret, your-s2s-secret, replace-me, and similar). Compose will not start when it is unset. Never commit a real value. Leave it empty in .env.example.
MCP_ALLOW_INSECURE_DEV	No	Set to 1 only for local development to start HTTP without CONDUIT_S2S_SECRET. The process logs a warning, does not enforce X-Gateway-S2S, and listens on 127.0.0.1 only (a wider MCP_HTTP_HOST is overridden). A placeholder secret is still refused.
AUTH_MODE	No	env (default) or gateway. Gateway mode requires X-CW-Company-Id, X-CW-Public-Key, X-CW-Private-Key, and X-CW-Client-Id on each /mcp request. env uses CW_MANAGE_* after S2S auth succeeds.

/health stays unauthenticated and does not read ConnectWise credentials. The stdio transport does not use CONDUIT_S2S_SECRET.

HTTP authentication

With MCP_TRANSPORT=http and CONDUIT_S2S_SECRET set, every /mcp request must include X-Gateway-S2S. The header value is:

t=<unix seconds>,v1=<hex hmac-sha256>

v1 is HMAC-SHA256 (hex, lowercase) of the ASCII string t=<unix seconds>, keyed with CONDUIT_S2S_SECRET. The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns 401. The process never writes the secret to logs.

X-Gateway-S2S: t=1710000000,v1=<hmac-sha256("t=1710000000")>

In AUTH_MODE=gateway, /mcp also requires X-CW-Company-Id, X-CW-Public-Key, X-CW-Private-Key, and X-CW-Client-Id (X-CW-URL is optional). Those headers are the credential source for that request. A request missing any required header returns 401.

Entra OAuth discovery routes stay available when MCP_OAUTH_ENABLED=true. POST /mcp still requires a valid X-Gateway-S2S header when the secret is set.

API Base URL (CW_MANAGE_URL)

Instance Type	URL
Cloud (North America)	https://api-na.myconnectwise.net (default)
Cloud (Europe)	https://api-eu.myconnectwise.net
Cloud (Australia)	https://api-au.myconnectwise.net
Self-hosted	https://cwm.yourcompany.com

For self-hosted instances, set CW_MANAGE_URL to your server's base URL. The server automatically appends /v4_6_release/apis/3.0 unless the URL already contains that path.

If your self-hosted instance uses a self-signed certificate, also set CW_MANAGE_REJECT_UNAUTHORIZED=false.

Getting Your API Keys

1. Log in to your ConnectWise Manage instance
2. Navigate to System > Members > API Members
3. Create a new API member with appropriate permissions
4. Generate API keys for the member
5. Get your Client ID from the ConnectWise Developer Portal

Available Tools

Interactive Ticket Card (MCP Apps)

cw_get_ticket renders as an interactive card in MCP Apps hosts (Claude Desktop/web) with an in-card "Add note" round-trip via cw_add_ticket_note that always posts internal-only (internalAnalysisFlag) notes; plain-JSON behavior is unchanged in other hosts. The card is neutral by default and brandable via window.__BRAND__ injection or MCP_BRAND_* env vars (MCP_BRAND_NAME, MCP_BRAND_LOGO_URL, MCP_BRAND_PRIMARY_COLOR, MCP_BRAND_ACCENT_COLOR, MCP_BRAND_BG, MCP_BRAND_TEXT) — no rebuild needed.

Tickets

• cw_search_tickets — Search service tickets with conditions
• cw_get_ticket — Get a ticket by ID
• cw_get_ticket_configurations — List configuration references associated with a service ticket (paged)
• cw_update_ticket_configurations — Add/remove ticket configuration associations in an ordered batch, reporting every outcome
• cw_create_ticket — Create a new service ticket. Optional parentTicketId (the same field cw_get_ticket returns) creates the ticket as a child of that parent.
• cw_update_ticket — Update a ticket (JSON Patch)
• cw_get_ticket_notes — Get all notes on a ticket (including child ticket notes)
• cw_add_ticket_note — Add a note to a ticket (discussion, internal, or resolution). Optional emailContactFlag, emailResourceFlag, emailCcFlag, and emailCc control who is emailed. Nothing is emailed unless one of those flags is set (or you set processNotifications). Omitting them does not email the contact. The create response reports internalFlag / externalFlag from the note type that was stored, so an internal note is not also reported as external.

Companies

• cw_search_companies — Search companies
• cw_get_company — Get a company by ID
• cw_create_company — Create a new company
• cw_update_company — Update a company (JSON Patch)

Contacts

• cw_search_contacts — Search contacts. Filter contact type with typeName, typeId, or childConditions (for example types/name = "Primary"). types / types/name in conditions is invalid and returns 400 ApiFindCondition because type is a child collection; the tool moves those clauses to childConditions. Contacts have firstName and lastName, not name. String values use double quotes (firstName = "Ada"); single quotes are accepted and rewritten.
• cw_get_contact — Get a contact by ID
• cw_create_contact — Create a new contact
• cw_update_contact — Update a contact (JSON Patch on PATCH /company/contacts/{id}). Paths include firstName, lastName, title, inactiveFlag, site, communicationItems (email and phone), and customFields. Contact types are not on this patch.
• cw_update_contact_types — Add or remove a contact type such as "Decision Maker" (POST / DELETE /company/contacts/{id}/typeAssociations). Adding a type the contact already has does not create a duplicate.

Projects

• cw_search_projects — Search projects
• cw_get_project — Get a project by ID
• cw_create_project — Create a new project
• cw_search_project_tickets — Search tickets under a project
• cw_get_project_ticket — Get a specific project ticket by ID
• cw_get_project_ticket_notes — Get all notes on a project ticket (including child ticket notes)
• cw_add_project_ticket_note — Add a note to a project ticket (discussion, internal, or resolution)

Time Entries

• cw_search_time_entries — Search time entries
• cw_get_time_entry — Get a time entry by ID
• cw_create_time_entry — Create a new time entry
• cw_update_time_entry — Correct a time entry (JSON Patch on PATCH /time/entries/{id}). Use this to fix actualHours when a metered agreement rounds to 0.25.
• cw_delete_time_entry — Delete a time entry (DELETE /time/entries/{id}). Manage rejects deletes of entries that are already billed.

Schedule Entries

• cw_search_schedule_entries — Search booked resource time
• cw_list_schedule_types — List schedule types (Service, Project, Sales, Meeting)
• cw_list_schedule_statuses — List schedule statuses (Tentative, Firm)
• cw_create_schedule_entry — Book resource time against a ticket, activity or project ticket
• cw_update_schedule_entry — Update a schedule entry (JSON Patch)

Members

• cw_search_members — Search members/technicians
• cw_get_member — Get a member by ID

Configuration Items

• cw_search_configurations — Search configuration items (assets)
• cw_get_configuration — Get a configuration item by ID

Service Reference Data

• cw_list_boards — List service boards
• cw_list_priorities — List ticket priorities
• cw_list_statuses — List statuses for a board

Activities

• cw_search_activities — Search activities
• cw_get_activity — Get an activity by ID
• cw_create_activity — Create a new activity

Agreements

• cw_search_agreements — Search agreements
• cw_get_agreement — Get an agreement by ID
• cw_get_agreement_additions — Get additions (line items) on an agreement
• cw_update_agreement_addition — Update an addition with JSON Patch (quantity, effectiveDate, cancelledDate, billCustomer, etc.); supports a dryRun preview that makes no write
• cw_create_agreement_addition — Create a new addition on an agreement
• cw_search_agreement_recaps — Search agreement billing recaps (used, remaining, overrun, next invoice)
• cw_get_agreement_recap — Get the billing recap for one agreement

Invoices

• cw_search_invoices — Search invoices (CW conditions, orderBy e.g. id desc)
• cw_get_invoice — Get an invoice by ID
• cw_update_invoice — Update one invoice with JSON Patch (PATCH /finance/invoices/{id}); returns the updated invoice in the same shape as cw_get_invoice. Allowed paths (leading slash optional): status/id or status ({ id }), attention, dueDate, date, reference, customerPO, internalNotes, billToCompany and billingSite (each as { id } or via /id; billToSite is accepted as an alias for Manage's billingSite). Manage invoices have no billToContact field — use attention for the contact name. Custom and payment fields are rejected before Manage is called. dryRun: true GETs the invoice, applies the patch in memory, and returns { dryRun: true, saved: false, preview } with no write. No batch mode — loop over ids (concurrency 3–5) and report per invoice. Resolve billing status names to ids first; never guess an id. Manage 400/401/403/404/409 errors pass through; 429 is retried once, and 5xx is retried once only when every operation is replace (a PATCH that includes add or remove retries only on 429). Requires the API member's role to have Finance › Invoices: Edit.

Procurement

• cw_search_purchase_orders — Search purchase orders
• cw_get_purchase_order — Get a purchase order by ID
• cw_get_purchase_order_items — Get the line items on a purchase order
• cw_search_procurement_products — Search procurement product items (SKUs placed on a ticket, project, order or opportunity)
• cw_get_procurement_product — Get a procurement product item by ID

Sales Orders

• cw_search_sales_orders — Search sales orders
• cw_get_sales_order — Get a sales order by ID
• cw_get_sales_order_products — Get the product items on a sales order

Opportunities

• cw_search_opportunities — Search opportunities
• cw_get_opportunity — Get an opportunity by ID
• cw_search_opportunity_forecasts — Search opportunity forecast lines
• cw_search_opportunity_notes — Search notes on an opportunity
• cw_search_sales_stages — List sales pipeline stages

Catalog (Products)

• cw_search_catalog_items — Search product catalog items
• cw_get_catalog_item — Get a catalog item by ID
• cw_create_catalog_item — Create a new catalog item
• cw_update_catalog_item — Update a catalog item (JSON Patch)
• cw_list_catalog_categories — List catalog categories
• cw_list_catalog_subcategories — List catalog subcategories
• cw_list_manufacturers — List manufacturers

Procurement Inventory

Warehouse stock and Inventory Adjustments. An adjustment is the only supported way to change on-hand quantities through the API: create the header, add the lines, then close it to post.

• cw_list_warehouses — List inventory warehouses
• cw_list_warehouse_bins — List warehouse bins, optionally for one warehouse
• cw_get_inventory_on_hand — Report every item with non-zero on-hand per bin, negatives included, with unit cost and extended value
• cw_list_adjustment_types — List inventory adjustment types
• cw_create_adjustment — Create an adjustment header (moves no stock)
• cw_add_adjustment_detail — Add one signed adjustment line, with serial numbers for serialised items
• cw_get_adjustment — Get an adjustment header with all of its detail lines
• cw_close_adjustment — Post the adjustment. Not reversible except by a counter-adjustment

Two limits of the ConnectWise API are worth knowing before using these. There is no summary field on an adjustment: the free-text fields are reason (max 100 characters) and notes. And no endpoint exposes an average cost, so the unitCost reported by cw_get_inventory_on_hand is the catalog item's own cost field, which is the standing cost rather than the weighted average cost ConnectWise values the stock at.

Health

• cw_test_connection — Test connection (hits /system/info)

Usage

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "connectwise-manage": {
      "command": "npx",
      "args": ["@wyre-ai/connectwise-manage-mcp"],
      "env": {
        "CW_MANAGE_COMPANY_ID": "your-company-id",
        "CW_MANAGE_PUBLIC_KEY": "your-public-key",
        "CW_MANAGE_PRIVATE_KEY": "your-private-key",
        "CW_MANAGE_CLIENT_ID": "your-client-id"
      }
    }
  }
}

For a self-hosted instance:

{
  "mcpServers": {
    "connectwise-manage": {
      "command": "npx",
      "args": ["@wyre-ai/connectwise-manage-mcp"],
      "env": {
        "CW_MANAGE_URL": "https://cwm.yourcompany.com",
        "CW_MANAGE_COMPANY_ID": "your-company-id",
        "CW_MANAGE_PUBLIC_KEY": "your-public-key",
        "CW_MANAGE_PRIVATE_KEY": "your-private-key",
        "CW_MANAGE_CLIENT_ID": "your-client-id",
        "CW_MANAGE_REJECT_UNAUTHORIZED": "false"
      }
    }
  }
}

With Docker

The checked-in Compose service is gateway mode. It does not set CW_MANAGE_* and does not use env_file, so a project .env cannot inject static vendor credentials into the container. Compose still interpolates CONDUIT_S2S_SECRET and LOG_LEVEL from that file. The image listens on 0.0.0.0 inside the container; the published port is loopback.

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up -d

Generate the secret with openssl rand -hex 32. Compose refuses to start when CONDUIT_S2S_SECRET is unset. Every /mcp request must carry X-Gateway-S2S (see HTTP authentication) plus the X-CW-* credential headers.

Single-tenant HTTP (AUTH_MODE=env) still requires the S2S secret, then uses CW_MANAGE_*:

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e CW_MANAGE_COMPANY_ID=your-company-id \
  -e CW_MANAGE_PUBLIC_KEY=your-public-key \
  -e CW_MANAGE_PRIVATE_KEY=your-private-key \
  -e CW_MANAGE_CLIENT_ID=your-client-id \
  -p 127.0.0.1:8080:8080 \
  ghcr.io/wyre-ai/connectwise-manage-mcp:latest

docker-compose.caddy.yml is that single-tenant shape behind Caddy. It still requires CONDUIT_S2S_SECRET.

HTTP Transport (Gateway Mode)

Run with HTTP transport for multi-tenant gateway deployments. The process exits until CONDUIT_S2S_SECRET is set:

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http AUTH_MODE=gateway node dist/index.js

Each /mcp request needs a valid X-Gateway-S2S header plus X-CW-Company-Id, X-CW-Public-Key, X-CW-Private-Key, and X-CW-Client-Id (X-CW-URL is optional).

Local HTTP without a secret is development-only. It binds 127.0.0.1 and logs a warning:

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development (stdio)
npm run dev

# HTTP refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http npm start

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

# Type check
npm run typecheck

# Run tests
npm test

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

Apache-2.0

---

Built by WYRE Technology — part of the MSP Claude Plugins ecosystem