ConnectWise PSA

mcp-connectwise-psa

ConnectWise PSA（Manage）向けの MCP（Model Context Protocol）サーバーです。技術者、ディスパッチャー、請求担当者を対象とする8つのツールセットにわたる厳選ツールに加え、APIのその他の機能を利用するための拡張手段と、オンプレミス環境向けの読み取り専用SQLツールセットを備えています。これにより、AI アシスタントは各役割に合った方法でPSAを操作できます。

• チケット — 検索／自分のチケット／メモ付きの詳細表示、作成、ステータス・優先度・担当者の更新、ディスカッション／内部メモの追加に加え、ボード・ステータス・優先度の検索と、チケットごとの作業時間およびタスクに対応します。サービスチケットとプロジェクトチケットの両方を扱います。ConnectWiseでは別々のリソースとして管理されているため、読み取りツールは両方を検索し、ID指定のツールはIDがどちらに属するかを判定します
• 時間 — チケットに作業時間を記録（作業ロール、作業タイプ、休憩時間用のConnectWiseのDeductに対応）、自分の作業時間を確認、作業ロールと作業タイプを検索し、タイムシートの一覧表示と提出ができます
• 会社と連絡先 — 素早い検索、連絡先の詳細（電話番号／メールアドレス）、会社の拠点
• 構成 — シリアル番号、IPアドレス、OS、保証情報を含むデバイス／資産（読み取り専用）
• ディスパッチ (スケジュール) — スケジュール項目（一覧表示／自分の予定／作成／再スケジュール／キャンセル）と、タイムゾーン、勤務時間、空き状況（空き／予約済み）を含むメンバー情報
• 請求 (財務、読み取り専用) — 請求書、契約、および請求可能な未請求の作業時間
• SQL (オンプレミスのみ) — RESTでは表現できない複数テーブルにまたがるレポート作成のため、cwwebapp_* Manageデータベースに対して直接読み取り専用のT-SQLを実行します。検索可能なスキーマカタログと、アシスタントが拡充できる保存済みクエリのライブラリも備えています。CW_DB_*を設定すると有効になります。有効な環境では、ツールセットを絞り込んでいないすべてのセッションで利用できます
• ツールセットとペルソナ — x-cw-toolsetsヘッダー（またはCW_TOOLSETS）を使って、セッションに必要なものだけを有効にできます。プリセットはtech／dispatch／invoicing／allです。デフォルトはallです。利用可能な機能を絞りたい場合は、セッションごとに設定してください。各ツールはツールセットを_meta.groupとして報告するため、アグリゲーター（MSPStackゲートウェイ）は機能ごとにツールをグループ化して切り替えられます
• メンバーごとのAPIキー（BYOK） — 各ユーザーが自分のConnectWiseメンバーキーを指定します。ConnectWiseはそのメンバーのセキュリティロールを適用し、書き込み操作はすべて実際の担当者に帰属します
• トランスポート — ローカル利用向けのstdio、共有デプロイ向けのストリーミング可能なHTTPに対応し、Dockerイメージも付属します

クイックスタート（ローカル、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の設定：

{
  "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"
      }
    }
  }
}

ConnectWise APIではclientIdが必要です。developer.connectwise.comで無料のインテグレーションを登録してください。APIメンバーキーは、ConnectWiseのMy Account → API Keys（メンバーごと）またはSystem → Members → API Members（インテグレーションアカウント）から作成します。

HTTPデプロイ

CW_SITE=… CW_COMPANY_ID=… CW_CLIENT_ID=… \
node dist/index.js --transport http --port 3000

または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

ルート	用途
POST/GET/DELETE /mcp	MCPストリーミング可能HTTPエンドポイント
GET /health	稼働状態の確認

セッションはメモリ上に保持されるため、インスタンスは1つだけ実行してください（またはスティッキーセッションを使用してください）。

アクセス制御 — キーの持ち込み（BYOK）

HTTP には MCP レベルのロールシステムはありません。各セッションでは、それぞれの ConnectWise メンバー API キーを提示し、ConnectWise 自体がアクセス制御を担います。メンバーのセキュリティロールによって処理が成功するかどうかが決まり、すべてのメモと時間エントリはそのメンバーに帰属します。

初期化リクエスト（およびセッション内の以降の各リクエスト）でキーを送信します。

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")

• キーを指定しないリクエストは 401 で拒否されます。2 つのキーのヘッダーは必ずセットで指定してください。
• キーがログに記録されることはありません。セッションはキーのペアの SHA-256 ハッシュにひも付けられます。同じセッション ID で別のペアを提示すると、403 が返されます。
• ConnectWise の My Account → API Keys でメンバー API キーを作成します。各技術者は自分のキーを使用します。

ローカルの stdio は単一ユーザー向けで、ヘッダーの代わりに環境変数の CW_PUBLIC_KEY／CW_PRIVATE_KEY を使用します。

ツールセット

ツールはツールセットにグループ化されているため、セッションには必要な機能だけが表示されます。ディスパッチャーに請求ツールは必要ありません。また、ツールの範囲を絞ることでアシスタントの集中力を保ち、コンテキストのコストを抑えられます。書き込みが実際に成功するかどうかは、引き続きメンバーの ConnectWise セキュリティロールによって決まります。

ツールセットキー	ツール
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（CW API 全体を検索 — 約 1,150 のエンドポイント）、cw_get（任意のパスに対する読み取り専用 GET）
sql (オンプレミス、CW_DB_* が必要)	cw_db_query（読み取り専用 T-SQL）、cw_db_find_table（スキーマカタログ）、cw_db_find_query／cw_db_save_query（保存済みクエリライブラリ）

プリセットでは、ペルソナごとにキーをまとめています。tech = tickets + time + companies + configurations · dispatch = tickets + schedule + companies + configurations · invoicing = finance + time + companies · all = すべてのキー。ペルソナのプリセットには意図的に sql を含めていません。技術者向けのツール群はデータベース向けのツール群ではないためです。

advanced ツールセットは、緊急時に使うための手段です（all には含まれますが、ペルソナのプリセットには含まれません）。cw_find_endpoint は ConnectWise API 全体を収録したカタログを検索し、cw_get は任意のパスに対して読み取り専用の GET を実行します。そのため、アシスタントは、厳選されたツールではカバーされていない幅広い領域（調達、営業、プロジェクト、システムなど）にもアクセスできます。これを除外するには、キーまたはペルソナのプリセットを指定してください（x-cw-toolsets: tech）。

キーとプリセットを組み合わせたカンマ区切りのリストでツールセットを選択します。

• HTTP — セッションごとに x-cw-toolsets ヘッダーを指定します。例：x-cw-toolsets: dispatch または x-cw-toolsets: tech,finance。
• stdio — CW_TOOLSETS 環境変数または --toolsets フラグを使用します。例：CW_TOOLSETS=invoicing。

デフォルトは all プリセットです。サーバーに設定されたすべての機能が含まれます。ツール群を絞りたいクライアントは、必要なキーまたはペルソナを指定します。CW_TOOLSETS／--toolsets 内の不明なキーは即座にエラーになりますが、x-cw-toolsets ヘッダー内の不明なトークンは無視されます。破壊的なツールは cw_delete_schedule_entry（dispatch）だけで、finance は読み取り専用です。cw_db_save_query は書き込みを行いますが、対象はクエリライブラリのファイルです。データベースへのアクセス自体は、権限によって SELECT のみに制限されています。

例外：sql ツールセット

ほかのすべてのツールセットは呼び出し元自身の ConnectWise キーで実行されるため、ConnectWise によって返されるデータがフィルタリングされます。sql は異なります。サーバー全体で使用する読み取り専用ログインを通じてデータベースを読み取るため、結果はメンバーに帰属せず、そのメンバーのセキュリティロール、ボードの制限、レコードの権限によるフィルタリングも受けません。

そのため、重要な判断は CW_DB_* を設定するかどうかです。サーバーにデータベースが設定されると、sql は通常のキーとなり、all に含まれ、デフォルトの選択にも含まれます。ツールセットを絞り込まないすべてのセッションが、PSA データベース全体を読み取れるようになります。CW_DB_* が設定されていないサーバーでは、これは通知なく除外されるため、利用する予定のないデプロイが影響を受けることはありません。

一部の呼び出し元にはデータベースアクセスを許可し、ほかには許可しない場合は、セッション単位（x-cw-toolsets: tech）で設定するか、サーバーの前段で制御してください。集約ゲートウェイを使えば、cw_db_* ツールを別の階層に分けられます。サーバー側で被害を抑えるのはログイン設定です。以下の運用手順を参照し、db_datareader のみに限定したうえで、認証情報の列を拒否してください。

SQL ツールセット（オンプレミスデータベース）

クラウドホスト型 ConnectWise ではデータベースにアクセスできないため、このツールセットはオンプレミスのデプロイ専用です。この目的だけに作成したログインを使って、Manage データベースを指定してください。

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

必要なのはこれだけです。データベースを設定すると、sql ツールセットはデフォルトの選択に含まれます。CW_DB_* が設定されていない状態で sql を指定すると起動時に失敗します（all のように、これを含むだけの選択では除外されます）。セッションでツールが実際に使われるまで、データベースへの接続は行われません。

まずレポートビューから始めてください。 ConnectWise には、ボード、ステータス、会社、連絡先をレコードにあらかじめ結合した、非正規化された v_rpt_* ビューが用意されています。例：v_rpt_service、v_rpt_time、v_rpt_company、v_rpt_invoices、v_rpt_agreementlist。cw_db_find_table はこれらのビューと、その基になるテーブルを把握しています。列一覧は INFORMATION_SCHEMA へのクエリを 1 回実行すれば正確に取得でき、使用中のバージョンに常に合った情報が得られるため、キー列のみを含みます。

保存済みクエリのライブラリは、コミット済みのコアと、CW_DB_QUERY_LIBRARY に指定する書き込み可能なオーバーレイ（JSON、{ version, queries[] }）で構成されます。オーバーレイのエントリはスラッグ単位で優先され、cw_db_save_query はそこに追記します。また、scripts/import-queries.mjs を使って、既存の BrightGauge エクスポートからライブラリを作成できます。

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

インポートしたクエリはこのリポジトリの外に保存されます。これらは利用者自身のレポートであり、会社名や料金が含まれる場合があるためです。コンテナーでは、保存済みクエリがコンテナーとともに消失しないよう、CW_DB_QUERY_LIBRARY にマウント済みストレージを指定してください。

ログインがセキュリティ境界です

ステートメントの検証はありません。サーバーはモデルの SQL をそのまま SQL Server に送信するため、実行される可能性がある操作はログインに許可されている操作そのものです。2 つのスクリプトで設定し、確認できます。

作成する — 先頭の 4 つの変数を編集し、sysadmin として実行します。@WhatIf のデフォルトは 1 なので、最初の実行では計画が表示されるだけです。

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

このスクリプトは、どのサーバーロールにも属さないログインを作成し、1 つのデータベースで db_datareader に追加し、それ以外のすべて（EXECUTE、すべての書き込み、DDL、BACKUP）を DENY します。また、スクリプトが検出した認証情報らしき列すべてに対する SELECT を DENY します。列名は Manage のバージョンによって変わり、MSP ごとに独自の列が追加されるため、名前をハードコードせずに検出します。再実行しても安全で、アップグレードでテーブルが追加された後に DENY を再適用する際にも使用できます。無効にする必要があるインスタンス全体の設定を報告しますが、変更はしません。xp_cmdshell を無効にすると他のアプリケーションに影響する場合があるため、判断は利用者に委ねられます。

確認する — 管理者ではなく、新しいログインとして実行します。

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

各チェックは PASS または FAIL を出力します。SELECT が機能すること、UPDATE／CREATE TABLE が拒否されること（DENY が漏れている場合に備え、必ずロールバックされるトランザクション内で実行）、xp_cmdshell／sp_OACreate／OPENROWSET(BULK …) にアクセスできないこと、認証情報の列が読み取れないこと、ログインが昇格されたロールに属していないことを確認します。FAIL が 1 つでもあれば、まだツールセットを有効にしないでください。

あらかじめ把握しておくべき重要な点が 2 つあります。

• 拒否された列があるテーブルでは SELECT * が失敗します。他の列は返されません。それが目的です。ツールのエラーを見たモデルは、列名を指定するようになります。
• 重要なのは EXECUTE 権限です。 この権限があると、「読み取り専用 SQL」が SQL Server サービスアカウントとしてのリモートコード実行に変わります。xp_cmdshell、sp_OACreate、sp_send_dbmail、NTLM 認証情報の取得に使われる xp_dirtree などが実行可能になります。OPENROWSET／BULK INSERT は EXECUTE 権限がなくてもファイルを読み取れるため、Ad Hoc Distributed Queries も無効にする必要があります。

運用上の注意：本番プライマリよりも、読み取り可能な AG セカンダリまたは復元済みのレポート用コピーを優先し、SQL ポートへの接続を MCP ホストのみにファイアウォールで制限してください。また、このログインに対する SQL Audit または Extended Events セッションを維持してください。

構成リファレンス

変数	デフォルト	用途
CW_SITE	—	ConnectWise ホスト（クラウドまたはオンプレミス。完全な URL も指定可能）
CW_COMPANY_ID	—	ログインする会社の ID
CW_CLIENT_ID	—	統合用 clientId
CW_PUBLIC_KEY / CW_PRIVATE_KEY	—	API メンバーキー — stdio では必須。HTTP では未使用（BYOK）
CW_MEMBER_IDENTIFIER	—	stdio キーに対応するメンバー（my-tickets/my-time）
TRANSPORT / PORT	stdio / 3000	トランスポートの選択
CW_TOOLSETS	all	有効にするツールセット（キー／プリセット）。HTTP では x-cw-toolsets を使ってセッションごとに上書き
CW_DB_HOST	—	ConnectWise SQL Server のホスト、または host\INSTANCE — sql ツールセットを有効化
CW_DB_NAME / CW_DB_USER / CW_DB_PASSWORD	—	データベースと、専用の読み取り専用ログイン（4 つすべてをまとめて指定する必要があります）
CW_DB_PORT	1433	TCP ポート。名前付きインスタンスと同時に指定することはできません
CW_DB_ENCRYPT / CW_DB_TRUST_SERVER_CERT	true / true	TLS、およびオンプレミスで一般的な自己署名証明書の受け入れ
CW_DB_READ_UNCOMMITTED	true	READ UNCOMMITTED で読み取り、レポート処理が本番の書き込みをブロックしないようにします
CW_DB_QUERY_TIMEOUT_MS / CW_DB_MAX_ROWS	30000 / 200	クエリごとのタイムアウトと行数上限
CW_DB_QUERY_LIBRARY	—	保存済みクエリを書き込めるファイルのパス。未設定の場合は組み込みクエリのみとなり、保存ツールは使用できません

注意事項と制限

• チケットの検索では、デフォルトでオープン中のチケットが対象になります。ステータス名とボード名は完全一致、テキストフィルターは部分一致です。
• サービスチケットとプロジェクトチケットは、ConnectWise の異なるリソースに保存されています。読み取りツールは ticket_type（デフォルトは both）を受け取り、結果を統合します。ID 指定のツールはデフォルトで auto に設定され、リソースを判別するために追加の検索が 1 回行われます。これを省略するには service または project を指定してください。cw_create_ticket が作成するのはサービスチケットのみです。プロジェクトチケットにはプロジェクトとフェーズが必要です。
• 記録した時間の範囲内に休憩がある場合は、time_end を実際の終了時刻のままにして、休憩時間を hours_deduct に指定します。代わりに短縮した hours を渡すと、ConnectWise で実際にはなかった終了時刻が表示されます。
• タイムスタンプの秒は整数で指定する必要があります。サーバーは値を正規化します（ConnectWise は小数秒を受け付けません）。
• 時間エントリーの日付に対応するオープン中の時間レポート期間が ConnectWise に必要です。存在しない場合、API のメッセージがそのまま返されます。
• 一部のオンプレミス版には /system/myAccount がありません。「自分のチケット」や「自分の時間」を使うには、メンバー識別子を明示的に指定してください（CW_MEMBER_IDENTIFIER または x-cw-member-id）。
• ディスカッションノートは顧客に表示されますが、内部ノートは表示されません。ツールではこの違いが明示されています。時間エントリーのノートは、チケットのディスカッション（add_to_detail）、内部分析（add_to_internal）、解決（add_to_resolution）のいずれかにコピーするか、コピーしないようにできます。結果には、どこにコピーされたかが示されます。3 つすべてをオフにした場合、ノートは時間エントリーに残ります。内部ノートになるわけではありません。
• cw_db_query は max_rows（デフォルトは 200）または約 20,000 文字の上限に達すると停止し、サーバー側でクエリをキャンセルします。応答には、どちらの上限に達したかが示されます。クエリごとのタイムアウトはデフォルトで 30 秒、最大で 120 秒です。
• データベース接続では READ UNCOMMITTED を使用するため、レポートのスキャンが技術者によるチケットの保存をブロックすることはありません。その代わり、ダーティーリードが発生し、同時書き込み中の件数は概算になります。レポートに正確な値が必要な場合は、CW_DB_READ_UNCOMMITTED=false を設定してください。
• DENY が設定された列を含むテーブルでは、SELECT * は失敗します。必要な列を指定してください。
• クラウドホスト版の ConnectWise ではデータベースにアクセスできません。sql ツールセットはオンプレミス版専用です。

開発

npm install
npm run dev          # stdio via tsx
npm run dev:http     # http via tsx
npm test             # vitest
npm run build        # tsc → dist/

ライセンス

MIT