Autotask

Autotask MCP サーバー

AI アシスタントから Autotask に直接アクセスできるようになります。 チケットの検索、作業時間の記録、会社情報の検索、プロジェクト管理などを、すべて自然言語で行えます。ブラウザーのタブとチャットウィンドウ間でコピー＆ペーストする必要はもうありません。

これは、Claude（または MCP 互換のあらゆる AI）を Autotask PSA 環境に接続する Model Context Protocol（MCP） サーバーです。AI アシスタントは、チケットのトリアージ、作業時間の記録、会社情報の検索、プロジェクト管理、請求内容の確認など、MSP チームが日常的に行う業務をカバーする 101 個のツールを利用できます。

Autotask を使って MSP を運営していて、作業中にアプリを切り替える手間にうんざりしているなら、これはあなたのためのものです。

MSP Claude Plugins エコシステムの一部です — Datto RMM、IT Glue、HaloPSA、ConnectWise Automate、NinjaOne、Huntress などを含む、MSP スタック向けの AI 連携機能を拡充するスイートです。MSP によって、MSP のために開発されました。

ワンクリックでデプロイ

注 — GitHub Packages のトークンは不要です。 ほとんどの WYRE MCP サーバーとは異なり、 autotask-mcp は GitHub Packages 上のプライベートな @wyre-ai/* パッケージに 依存していません。WYRE の依存関係は autotask-node SDK のみで、パブリックな WYRE-AI/autotask-node リポジトリへの Git 依存関係として宣言されており、 npm install が匿名で解決します。そのため、DigitalOcean のワンクリックデプロイは NODE_AUTH_TOKEN／GITHUB_TOKEN のビルド変数なしで動作します。

クイックスタート

Claude Desktop — ダウンロードして開くだけです。

1. 最新リリース から autotask-mcp.mcpb をダウンロードします
2. ファイルを開きます（ダブルクリックするか、Claude Desktop にドラッグします）
3. プロンプトが表示されたら、Autotask の認証情報（Username、Secret、Integration Code）を入力します

ターミナルも JSON の編集も Node.js のインストールも不要です。

Claude Code（CLI）：

claude mcp add autotask-mcp \
  -e [email protected] \
  -e AUTOTASK_SECRET=your-secret \
  -e AUTOTASK_INTEGRATION_CODE=your-code \
  -- npx -y github:WYRE-AI/autotask-mcp

Docker を使った方法とソースからのインストール方法については、インストール を参照してください。

機能

• 🔌 MCP プロトコル準拠: MCP のリソースとツールを完全にサポートします
• 🎴 インタラクティブなチケットカード（MCP Apps）: autotask_get_ticket_details は、MCP Apps ホスト（Claude Desktop/web）でインタラクティブなカードとして表示され、カード内で「Add note」を使った往復処理に対応します。デフォルトではニュートラルなテーマで、MCP_BRAND_* 環境変数でブランドに合わせて変更できます。他のホストでのプレーンな JSON の動作に変更はありません
• 🛠️ 包括的な API 対応: 会社、連絡先、チケット、プロジェクト、請求項目、タイムエントリ、メモ、添付ファイルなどにわたる 101 個のツールを提供します
• 🔍 高度な検索: すべてのエンティティを対象に、フィルターを使った強力な検索機能を利用できます
• 📝 CRUD 操作: Autotask の主要なエンティティに対して、作成、読み取り、更新の操作を行えます
• 🔄 ID から名前へのマッピング: 会社 ID とリソース ID を、人が読みやすい名前に自動的に解決します
• ⚡ インテリジェントなキャッシュ: パフォーマンスの向上と API 呼び出しの削減を実現するスマートキャッシュシステムです
• 🔒 セキュアな認証: Autotask の認証情報を使用したエンタープライズグレードの API セキュリティを提供します
• 🌐 デュアルトランスポート: stdio（ローカル）と HTTP Streamable（リモート／Docker）の両方のトランスポートをサポートします
• 📦 MCPB パッケージ: MCP Bundle を使ってデスクトップクライアントにワンクリックでインストールできます
• 🐳 Docker 対応: HTTP トランスポートとヘルスチェックを備えたコンテナーデプロイに対応します
• 📊 構造化ログ: レベルと形式を設定できる包括的なロギングを提供します
• 🧪 テストカバレッジ: 80% 以上のカバレッジを備えた包括的なテストスイートです

目次

• インストール
• 設定
  • ゲートウェイモード
• 使用方法
• API リファレンス
• ID から名前へのマッピング
• HTTP トランスポート
• Docker デプロイ
• 移行ガイド
• 開発
• テスト
• トラブルシューティング
• 貢献
• コントリビューター
• ライセンス

インストール

オプション 1: MCPB Bundle（Claude Desktop）

最も簡単な方法です。ターミナルも JSON の編集も不要で、Node.js のインストールも必要ありません。

1. 最新リリースから autotask-mcp.mcpb をダウンロードします
2. ファイルを開きます（ダブルクリックするか、Claude Desktop にドラッグします）
3. プロンプトが表示されたら、Autotask の認証情報（ユーザー名、シークレット、インテグレーションコード）を入力します

**Claude Code（CLI）**の場合は、コマンドを 1 つ実行するだけです。

claude mcp add autotask-mcp \
  -e [email protected] \
  -e AUTOTASK_SECRET=your-secret \
  -e AUTOTASK_INTEGRATION_CODE=your-code \
  -- npx -y github:WYRE-AI/autotask-mcp

オプション 2: Docker

ローカル（stdio — Claude Desktop または Claude Code 用）:

{
  "mcpServers": {
    "autotask": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "[email protected]",
        "-e", "AUTOTASK_SECRET=your-secret",
        "-e", "AUTOTASK_INTEGRATION_CODE=your-code",
        "--entrypoint", "node",
        "ghcr.io/wyre-ai/autotask-mcp:latest",
        "dist/entry.js"
      ]
    }
  }
}

リモート（HTTP Streamable — サーバーデプロイ用）:

docker run -d \
  --name autotask-mcp \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="your-real-s2s-secret" \
  -e AUTOTASK_USERNAME="[email protected]" \
  -e AUTOTASK_SECRET="your-secret" \
  -e AUTOTASK_INTEGRATION_CODE="your-code" \
  --restart unless-stopped \
  ghcr.io/wyre-ai/autotask-mcp:latest

# Verify (health does not require X-Gateway-S2S)
curl http://127.0.0.1:8080/health

CONDUIT_S2S_SECRET が空、または既知のプレースホルダーの場合、HTTP サーバーは起動を拒否します。クライアントは MCP Streamable HTTP トランスポートを使用して http://127.0.0.1:8080/mcp に接続し、X-Gateway-S2S を送信する必要があります。X-Gateway-S2S 署名を参照してください。

ゲートウェイモード（MCP Gateway デプロイ用）:

HTTP ヘッダー経由で認証情報を注入する MCP Gateway の背後にデプロイする場合に使用します。このコンテナーには静的な Autotask 認証情報がありません。

docker run -d \
  --name autotask-mcp \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="your-real-s2s-secret" \
  -e AUTH_MODE=gateway \
  --restart unless-stopped \
  ghcr.io/wyre-ai/autotask-mcp:latest

ゲートウェイはヘッダー経由で認証情報を注入します。

• X-Gateway-S2S: サービス間認証（/mcp で必須）
• X-API-Key: Autotask のユーザー名
• X-API-Secret: Autotask のシークレット
• X-Integration-Code: Autotask のインテグレーションコード
• X-Impersonation-Resource-Id: （任意）代理で操作する Autotask リソース ID

3 つの Autotask ヘッダーのいずれかを欠く /mcp リクエストは 401 を返し、環境変数の AUTOTASK_* にはフォールバックしません。詳しくはゲートウェイモードを参照してください。

オプション 3: ソースから（開発用）

git clone https://github.com/WYRE-AI/autotask-mcp.git
cd autotask-mcp
npm ci && npm run build

次に、MCP クライアントの接続先を dist/entry.js に設定します。

{
  "mcpServers": {
    "autotask": {
      "command": "node",
      "args": ["/path/to/autotask-mcp/dist/entry.js"],
      "env": {
        "AUTOTASK_USERNAME": "[email protected]",
        "AUTOTASK_SECRET": "your-secret",
        "AUTOTASK_INTEGRATION_CODE": "your-code"
      }
    }
  }
}

前提条件

• 有効な Autotask API 認証情報（API ユーザーのメールアドレス、シークレット、インテグレーションコード）
• MCP 対応クライアント（Claude Desktop、Claude Code など）
• Docker（オプション 2 の場合）または Node.js 18 以降（オプション 3 の場合）

設定

環境変数

設定を記述した .env ファイルを作成します。

# Required Autotask API credentials (Local Mode)
[email protected]
AUTOTASK_SECRET=your-secret-key
AUTOTASK_INTEGRATION_CODE=your-integration-code

# Optional configuration
# AUTOTASK_API_URL is auto-detected from AUTOTASK_USERNAME via Autotask's
# unauthenticated zoneInformation endpoint on first connect. Only set this
# explicitly to override auto-detection (e.g. for an on-prem proxy).
# AUTOTASK_API_URL=https://webservices2.autotask.net/atservicesrest/
MCP_SERVER_NAME=autotask-mcp

# Authentication mode
AUTH_MODE=env               # env (local), gateway (hosted)

# Required to start HTTP. Empty and known placeholders are rejected.
# Never commit a real value. stdio does not use this.
CONDUIT_S2S_SECRET=

# Local HTTP only. Exactly "1" skips X-Gateway-S2S and forces 127.0.0.1.
# MCP_ALLOW_INSECURE_DEV=1

# Transport (stdio for local/desktop, http for remote/Docker)
MCP_TRANSPORT=stdio          # stdio, http
MCP_HTTP_PORT=8080           # HTTP transport port (only used when MCP_TRANSPORT=http)
# Honored when CONDUIT_S2S_SECRET is set. Without a usable secret the bind is 127.0.0.1.
MCP_HTTP_HOST=0.0.0.0        # HTTP transport bind address

# Logging
LOG_LEVEL=info          # error, warn, info, debug
LOG_FORMAT=simple       # simple, json

# Search-result name enrichment
# Max concurrent Autotask API calls used to resolve company/resource names on
# search results. Kept low to stay under Autotask's per-integration
# concurrent-thread limit (raising it risks HTTP 429 "thread threshold").
AUTOTASK_ENHANCE_CONCURRENCY=3

# Max Autotask REST calls in flight per tenant. Further calls queue instead of
# tripping the concurrent-thread limit (HTTP 429 "thread threshold").
AUTOTASK_MAX_INFLIGHT=3

# Environment
NODE_ENV=production

ゲートウェイモード

MCP ゲートウェイ（例：mcp.wyre.ai）の背後にデプロイすると、サーバーはゲートウェイモードで動作し、各リクエストの HTTP ヘッダー経由で認証情報が注入されます。

ゲートウェイモードを有効にする：

AUTH_MODE=gateway
MCP_TRANSPORT=http
CONDUIT_S2S_SECRET=<gateway-provisioned secret>

すべての /mcp リクエストには、有効な X-Gateway-S2S ヘッダーと3つの Autotask 認証情報ヘッダーが必要です。いずれかの認証情報ヘッダーがないリクエストは 401 を返します。サーバーは、プロセス環境内の AUTOTASK_USERNAME、AUTOTASK_SECRET、AUTOTASK_INTEGRATION_CODE にはフォールバックしません。

必要なヘッダー：

ヘッダー	説明
X-Gateway-S2S	サービス間の証明。t=<unix seconds>,v1=<hex hmac-sha256>。CONDUIT_S2S_SECRET が設定されている場合、/mcp で必須です。X-Gateway-S2S の署名を参照してください。
X-API-Key	Autotask API のユーザー名（メールアドレス）
X-API-Secret	Autotask API のシークレットキー
X-Integration-Code	Autotask のインテグレーションコード
X-API-URL	（任意）カスタム Autotask API URL
X-Impersonation-Resource-Id	（任意）代理で操作する Autotask リソース ID。Autotask には ImpersonationResourceId ヘッダーとして転送されるため、アクションは API ユーザーではなくそのリソースに帰属し、エンティティの読み取り専用フィールド impersonatorCreatorResourceID に記録されます。正の整数である必要があります。それ以外の値は警告とともに無視されます。代理対象のリソース自身がそのアクションの権限を持ち、API ユーザーのセキュリティレベルで代理操作が許可されている必要があります。

X-Gateway-S2S の署名

MCP_TRANSPORT=http の場合、CONDUIT_S2S_SECRET に実際のシークレットが設定されていないと起動しません。空の値や、changeme、placeholder、your-s2s-secret、secret、password、test などの既知のプレースホルダー、および未解決の ${...} テンプレートのみで構成される値は拒否されます。プロセスはエラーをログに記録し、ゼロ以外の終了コードで終了します。シークレットが出力されることはありません。

MCP_ALLOW_INSECURE_DEV=1 はローカル専用の回避策です。プロセスは警告をログに記録し、X-Gateway-S2S をチェックせず、127.0.0.1 のみで待ち受けます。このモードでは、ループバック以外の MCP_HTTP_HOST（0.0.0.0、localhost、::1 を含む）は無視され、その上書きがログに記録されます。

使用可能なシークレットがない場合、バインドアドレスはデフォルトで 127.0.0.1 になります。シークレットが設定されている場合は、MCP_HTTP_HOST が適用されます（この変数が未設定の場合のデフォルトは 0.0.0.0 で、コンテナーイメージではこの値が設定されています）。プロキシが前段にない限り、ホストポートはループバックで公開してください。

/health は認証なしで利用でき、認証情報を読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

使用可能なシークレットがある場合、すべての /mcp リクエストには次のヘッダーが必要です。

X-Gateway-S2S: t=<unix seconds>,v1=<lowercase hex>

v1 は、CONDUIT_S2S_SECRET をキーとして、ASCII 文字列 t=<unix seconds>（ヘッダーの先頭にある同じ t= プレフィックス）に対して計算し、16進数でエンコードした HMAC-SHA256 です。タイムスタンプはサーバーの時計と300秒以内の差である必要があります。ヘッダーがない場合、または無効な場合、HTTP 401 が返されます。シークレットがログやレスポンス本文に書き込まれることはありません。

# t is the current unix time. v1 is HMAC-SHA256 of the literal "t=$t".
t=$(date +%s)
v1=$(printf 't=%s' "$t" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Gateway-S2S: t=${t},v1=${v1}" \
  -H "X-API-Key: [email protected]" \
  -H "X-API-Secret: the-api-secret" \
  -H "X-Integration-Code: the-integration-code" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=env の場合でも、/mcp には有効な X-Gateway-S2S ヘッダーが必要です。この場合、Autotask の認証情報は AUTOTASK_* から取得されます。AUTH_MODE=gateway の場合は、上記の3つの X-API-* ヘッダーも必須であり、そのリクエストの認証情報はこれらのヘッダーのみから取得されます。

ヘルスチェックレスポンス（ゲートウェイモード）：

{
  "status": "ok",
  "transport": "http",
  "authMode": "gateway",
  "timestamp": "2026-02-05T10:00:00.000Z"
}

移行手順の詳細は、移行ガイドを参照してください。

💡 プロのヒント：上記の内容をプロジェクトのルートにある .env ファイルにコピーしてください。

Autotask API のセットアップ

1. API ユーザーの作成：Autotask で、適切な権限を持つ専用の API ユーザーを作成します
2. シークレットの生成：そのユーザー用の API シークレットを生成します
3. インテグレーションコード：Autotask からインテグレーションコードを取得します
4. 権限：API ユーザーが必要なエンティティへの読み取り／書き込みアクセス権を持っていることを確認します

セットアップ手順の詳細は、Autotask API のドキュメントを参照してください。

使用方法

コマンドライン

# Start the MCP server (stdio transport, for piping to an MCP client)
node dist/entry.js

# HTTP refuses to start until CONDUIT_S2S_SECRET is a real secret
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http node dist/index.js

# Local HTTP only, without a service-to-service secret (always binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 MCP_TRANSPORT=http node dist/index.js

MCP クライアントの設定

すべてのセットアップ方法については、インストールを参照してください。

API リファレンス

リソース

リソースを使用すると、Autotask データに読み取り専用でアクセスできます。

• autotask://companies - すべての会社を一覧表示
• autotask://companies/{id} - 特定の会社を取得
• autotask://contacts - すべての連絡先を一覧表示
• autotask://contacts/{id} - 特定の連絡先を取得
• autotask://tickets - すべてのチケットを一覧表示
• autotask://tickets/{id} - 特定のチケットを取得
• autotask://time-entries - 時間エントリーを一覧表示

ツール

サーバーは、Autotask と連携するための 101 個のツールを提供します。

会社の操作

• autotask_search_companies - フィルターを指定して会社を検索
• autotask_create_company - 会社を新規作成
• autotask_update_company - 既存の会社を更新

連絡先の操作

• autotask_search_contacts - フィルターを指定して連絡先を検索
• autotask_create_contact - 連絡先を新規作成

チケットの操作

• autotask_search_tickets - フィルターを指定してチケットを検索
• autotask_get_ticket_details - ID でチケットの詳細をすべて取得
• autotask_create_ticket - チケットを新規作成

時間エントリーの操作

• autotask_create_time_entry - 時間エントリーを記録
• autotask_search_time_entries - フィルター（リソース、チケット、タスク、日付範囲）を指定して時間エントリーを検索

請求項目（承認・転記ワークフロー）

• autotask_search_billing_items - 承認済みおよび転記済みの請求項目を検索
• autotask_get_billing_item - ID で特定の請求項目を取得
• autotask_search_billing_item_approval_levels - 時間エントリーの複数レベルの承認記録を検索

プロジェクトの操作

• autotask_search_projects - フィルターを指定してプロジェクトを検索
• autotask_create_project - プロジェクトを新規作成

リソースの操作

• autotask_search_resources - リソース（技術者／ユーザー）を検索

ノートの操作

• autotask_get_ticket_note / autotask_search_ticket_notes / autotask_create_ticket_note
• autotask_get_project_note / autotask_search_project_notes / autotask_create_project_note
• autotask_get_company_note / autotask_search_company_notes / autotask_create_company_note

添付ファイルの操作

• autotask_get_ticket_attachment - チケットの添付ファイルを取得
• autotask_search_ticket_attachments - チケットの添付ファイルを検索
• autotask_get_ticket_note_attachment - チケットのノートに添付されたファイルを取得（貼り付けたスクリーンショットなど）
• autotask_search_ticket_note_attachments - チケットのノートの添付ファイルを検索

財務の操作

• autotask_get_expense_report / autotask_search_expense_reports / autotask_create_expense_report
• autotask_get_quote / autotask_search_quotes / autotask_create_quote
• autotask_get_opportunity / autotask_search_opportunities / autotask_create_opportunity
• autotask_update_opportunity - 商談を更新（ステージ、ステータス、売上／コスト明細、UDF）
• autotask_search_invoices - 請求書を検索

契約の操作

• autotask_search_contracts - 契約を検索（名前、会社、ステータス、種類、終了日の範囲）
• autotask_get_contract - ID で単一の契約を取得
• autotask_list_expiring_contracts - 期限切れ間近／期限切れの契約レポート（今後 N 日以内、会社単位または組織全体）
• autotask_create_contract / autotask_create_contracts_bulk - 契約の基本情報を 1 件または複数件作成
• autotask_update_contract - 契約を更新（終了日の延長／更新など）
• autotask_create_contract_service / autotask_update_contract_service - 契約のサービス明細を管理

構成アイテム

• autotask_search_configuration_items - 構成アイテム（資産）を検索

タスクの操作

• autotask_search_tasks - プロジェクトのタスクを検索
• autotask_create_task - プロジェクトのタスクを作成

ユーティリティの操作

• autotask_test_connection - API の接続をテスト

ツールの使用例

// Search for companies
{
  "name": "autotask_search_companies",
  "arguments": {
    "searchTerm": "Acme Corp",
    "isActive": true,
    "pageSize": 10
  }
}

// Create a new ticket
{
  "name": "autotask_create_ticket",
  "arguments": {
    "companyID": 12345,
    "title": "Server maintenance request",
    "description": "Need to perform monthly server maintenance",
    "priority": 2,
    "status": 1
  }
}

ID-to-Name マッピング

Autotask MCP サーバーには、会社 ID とリソース ID を人が読みやすい名前に自動で解決するインテリジェントな ID-to-Name マッピングが含まれており、API レスポンスを AI アシスタントや人間のユーザーにとって、より有用なものにします。

自動拡張

すべての検索ツールと詳細ツールには、解決された名前を含む _enhanced フィールドが自動的に追加されます。

{
  "id": 12345,
  "title": "Sample Ticket",
  "companyID": 678,
  "assignedResourceID": 90,
  "_enhanced": {
    "companyName": "Acme Corporation",
    "assignedResourceName": "John Smith"
  }
}

仕組み

ID-to-Name マッピングは、すべての検索ツールと詳細ツールの結果に自動で適用されます。追加のツールは必要ありません。会社 ID またはリソース ID を含むすべてのレスポンスに、_enhanced フィールドが透過的に追加されます。

パフォーマンス機能

• スマートキャッシュ：API 呼び出しを減らすため、名前は 30 分間キャッシュされます
• 一括処理：複数の ID を効率的に一括検索します
• フォールバック処理：検索に失敗した場合は「Unknown Company (123)」を返します
• 並列処理：複数のマッピングを同時に解決します

マッピングのテスト

マッピング機能をテストします。

npm run test:mapping

詳細なマッピングのドキュメントについては、docs/mapping.md を参照してください。

HTTP トランスポート

このサーバーは、リモート環境へのデプロイ（Docker、クラウドホスティングなど）に対応する MCP Streamable HTTP トランスポートをサポートしています。有効にするには MCP_TRANSPORT=http を設定します。

# Start with HTTP transport (exits unless CONDUIT_S2S_SECRET is a real secret)
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" MCP_TRANSPORT=http MCP_HTTP_PORT=8080 node dist/index.js

HTTP トランスポートでは、以下が公開されます。

• POST /mcp — MCP Streamable HTTP エンドポイントです。CONDUIT_S2S_SECRET が設定されている場合は、X-Gateway-S2S が必要です。X-Gateway-S2S 署名を参照してください。
• GET /health — 認証なしで利用できるヘルスチェックです（{"status":"ok"} を返します）。認証情報は読み取りません。

クライアントは、MCP Streamable HTTP 仕様に従い、Accept: application/json, text/event-stream ヘッダーを付けて /mcp にリクエストを送信する必要があります。

Docker デプロイ

Docker イメージは、組み込みのヘルスチェックとともに、デフォルトで HTTP トランスポート（ポート 8080）を使用します。

GitHub Container Registry のビルド済みイメージを使用する

Docker イメージは、デフォルトでポート 8080 の HTTP トランスポートを使用します。クライアントがネットワーク経由で接続する、リモート環境またはサーバー環境へのデプロイに適しています。

# Pull the latest image
docker pull ghcr.io/wyre-ai/autotask-mcp:latest

# Run container with HTTP transport (default). The image binds 0.0.0.0 inside
# the container; publish on loopback and pass the S2S secret.
docker run -d \
  --name autotask-mcp \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTOTASK_USERNAME="[email protected]" \
  -e AUTOTASK_SECRET="your-secret-key" \
  -e AUTOTASK_INTEGRATION_CODE="your-integration-code" \
  --restart unless-stopped \
  ghcr.io/wyre-ai/autotask-mcp:latest

# Verify it's running (health does not require X-Gateway-S2S)
curl http://127.0.0.1:8080/health

CONDUIT_S2S_SECRET が未設定の場合、Compose は起動しません。チェックイン済みのゲートウェイサービスでは AUTH_MODE=gateway を設定し、127.0.0.1:8080:8080 を公開します。また、AUTOTASK_* は注入しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

Claude Desktop で stdio を使用する方法については、インストールオプション 2を参照してください。

クイックスタート（ソースから）

# Clone repository
git clone https://github.com/WYRE-AI/autotask-mcp.git
cd autotask-mcp

# Create environment file
cp .env.example .env
# Edit .env with your credentials

# Start with docker-compose
docker compose up -d

本番環境へのデプロイ

# Build production image locally
docker build -t autotask-mcp:latest .

# Run container
docker run -d \
  --name autotask-mcp \
  --env-file .env \
  --restart unless-stopped \
  autotask-mcp:latest

開発モード

# Start development environment with hot reload
docker compose --profile dev up autotask-mcp-dev

開発

セットアップ

git clone https://github.com/WYRE-AI/autotask-mcp.git
cd autotask-mcp
npm install

利用可能なスクリプト

npm run dev          # Start development server with hot reload
npm run build        # Build for production
npm run test         # Run test suite
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage
npm run lint         # Run ESLint
npm run lint:fix     # Fix ESLint issues

プロジェクト構成

autotask-mcp/
├── src/
│   ├── handlers/           # MCP request handlers
│   ├── mcp/               # MCP server implementation
│   ├── services/          # Autotask service layer
│   ├── types/             # TypeScript type definitions
│   ├── utils/             # Utility functions (config, logger, cache)
│   ├── entry.ts           # Entry point (stdout guard + .env loader)
│   └── index.ts           # Server bootstrap (config, logger, server init)
├── tests/                 # Test files
├── scripts/               # Build and packaging scripts
│   └── pack-mcpb.js       # MCPB bundle creation
├── manifest.json          # MCPB manifest for desktop distribution
├── Dockerfile             # Container definition (HTTP transport)
├── docker-compose.yml     # Multi-service orchestration
└── package.json          # Project configuration

テスト

テストの実行

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

# Run specific test file
npm test -- tests/autotask-service.test.ts

テストカテゴリ

• 単体テスト：サービスレイヤーとユーティリティ関数
• 統合テスト：MCP プロトコルへの準拠
• API テスト：Autotask API との連携（認証情報が必要です）

カバレッジ要件

• すべての指標で最低 80% のカバレッジ
• 重要な処理経路（認証、データ処理）は 100% のカバレッジ

設定リファレンス

環境変数

変数	必須	デフォルト	説明
AUTOTASK_USERNAME	✅	-	Autotask API のユーザー名（メールアドレス）
AUTOTASK_SECRET	✅	-	Autotask API のシークレットキー
AUTOTASK_INTEGRATION_CODE	✅	-	Autotask のインテグレーションコード
AUTOTASK_API_URL	❌	自動検出	Autotask API のエンドポイント URL
MCP_SERVER_NAME	❌	autotask-mcp	MCP サーバー名
MCP_TRANSPORT	❌	stdio	トランスポートの種類（stdio または http）
MCP_HTTP_PORT	❌	8080	HTTP トランスポートのポート
MCP_HTTP_HOST	❌	シークレットが設定されている場合は 0.0.0.0、設定されていない場合は 127.0.0.1	HTTP のバインドアドレス。CONDUIT_S2S_SECRET が設定されている場合、この変数が適用されます。MCP_ALLOW_INSECURE_DEV=1 を設定すると、127.0.0.1 が強制されます。
CONDUIT_S2S_SECRET	HTTP では必須	—	X-Gateway-S2S 用のサービス間シークレットです。空の場合、または既知のプレースホルダーの場合、HTTP は終了します。実際の値をコミットしないでください。
MCP_ALLOW_INSECURE_DEV	❌	未設定	使用可能なシークレットなしでローカル HTTP を使用する場合は、1 を正確に設定します。警告をログに記録し、X-Gateway-S2S を省略して、127.0.0.1 のみでリッスンします。
LOG_LEVEL	❌	info	ログレベル
LOG_FORMAT	❌	simple	ログの出力形式
AUTOTASK_ENHANCE_CONCURRENCY	❌	3	検索結果の会社名／リソース名を解決するために使用する、Autotask API 呼び出しの最大同時実行数です。Autotask の同時スレッド数の上限を超えないよう、低く設定されています。
AUTOTASK_MAX_INFLIGHT	❌	3	テナントごとに実行中にできる Autotask REST 呼び出しの最大数です。上限を超える呼び出しは、同時スレッド数の上限に抵触しないよう、HTTP クライアント内でキューに入ります。
NODE_ENV	❌	development	Node.js の環境

ログレベル

• error：エラーメッセージのみ
• warn：警告とエラー
• info：一般情報、警告、エラー
• debug：詳細なデバッグ情報

ログ形式

• simple：人が読みやすいコンソール出力
• json：構造化された JSON 出力（本番環境に推奨）

レート制限

Autotask は、ローリング 1 時間枠でインテグレーションコードごとの API しきい値を適用します。

• 約 10,000 リクエスト／時（ソフト） — 警告メールが送信され、断続的に HTTP 429 が返されます
• 約 20,000 リクエスト／時（ハード） — 時間枠が更新されるまで HTTP 429 が継続して返されます

LLM 主導のワークフローでは、リクエストが容易に大量発生します。「メモ付きで、すべての進行中プロジェクトのステータスレポートを作成」といった処理では、数分間に数百件のリクエストが発生することがあります。サーバーは、これをより安全に処理するため、次の対策を行います。

• 429 応答は、構造化エラーとして通知されます。 ツールの結果には error_type: "rate_limited" と、Autotask の Retry-After ヘッダーから解析した retry_after_seconds フィールドが含まれます。エラーメッセージには、LLM に再試行せず、クエリの範囲を絞るようユーザーに尋ねることが明記されています。これにより、再試行を繰り返してクールダウンが延長されるのを防ぎます。
• 同時スレッド数による 429 は、1 分間のクールダウンではなくキューに入ります。 Autotask は、インテグレーションがスレッド数のしきい値を超えた場合にも HTTP 429 を返します（本文に「thread threshold」と記載されます）。これは、時間単位のクォータとは別の、バーストによる問題です。HTTP クライアントではテナントごとに最大 AUTOTASK_MAX_INFLIGHT 件（デフォルトは 3）の呼び出しを実行中にでき、それを超える呼び出しはキューに入ります。べき等な呼び出し（GET、DELETE、または POST /{Entity}/query）でスレッド数のしきい値による 429 が発生した場合は、短いバックオフを挟んで再試行され、60 秒のクールダウンは開始されません。時間単位のしきい値による 429 では、引き続きクールダウンが開始されます。作成／更新の呼び出しは自動的に再試行されません。
• 複数の対象に処理を展開するツールの説明には、レート制限に関するヒントが含まれます。 繰り返し処理されることの多いツール（autotask_search_ticket_notes、autotask_search_project_notes、autotask_search_company_notes、autotask_search_time_entries、autotask_search_ticket_attachments、autotask_search_ticket_note_attachments）には、反復処理の前に親レコードの一覧を絞り込むよう LLM に促すヒントが含まれます。

制限の引き上げ

Autotask では、連携ごとのしきい値を引き上げられます。

1. Autotask Admin → Resources/Users (HR) → Resources
2. 専用の API ユーザーを編集 → Workflow Rules → API Tracking Identifier
3. MCP サーバーが使用する連携コードのしきい値を調整します

これは、Claude／Copilot などと他のツールで単一の連携コードを共有している場合に適した方法です。LLM を多用するワークロードでは、専用の API ユーザー（および連携コード）を用意し、1 つのクライアントからのファンアウトによって他のクライアントがリソース不足にならないようにします。

役立つパターン

• ノート、作業時間、添付ファイルを検索する場合は、必ず日付範囲を指定してください。30 日間の範囲でも、呼び出し回数を桁違いに減らせることがあります。
• 親レコードの検索結果をキャッシュします。 100 件のチケットを順に処理する場合は、チケット一覧を一度だけ取得して後続のクエリで再利用し、子レコードごとに再検索しないでください。
• セッションごとに値を一度だけ取得し、呼び出しのたびに再取得しないよう、autotask_get_field_info を使用して選択リストの値を確認してください。

Autotask からしきい値の警告が表示される一方でサーバーに問題がない場合、LLM ドライバーがファンアウトパターンでリクエストを発行している可能性があります。反復処理を始める前に検索対象を絞るよう、プロンプトを調整してください。

トラブルシューティング

よくある問題

認証エラー

Error: Missing required Autotask credentials

解決策：必要な環境変数がすべて正しく設定されていることを確認してください。

接続タイムアウト

Error: Connection to Autotask API failed

解決策：

• ネットワーク接続を確認します
• API エンドポイント URL を確認します
• API ユーザーに適切な権限があることを確認します

アクセス拒否

Error: User does not have permission to access this resource

解決策：Autotask API ユーザーの権限とセキュリティレベルの設定を確認してください。

デバッグモード

詳細なトラブルシューティングのためにデバッグログを有効にします：

LOG_LEVEL=debug npm start

ヘルスチェック

サーバーの接続をテストします：

# Run test suite
npm run test

# For HTTP transport, check the health endpoint
curl http://localhost:8080/health
# Returns: {"status":"ok"}

# Test API connection with debug logging
LOG_LEVEL=debug npm start

Autotask API のレート制限

問題：Claude が頻繁にクエリを実行した際に、429 Too Many Requests または「thread limit exceeded」エラーが発生する

Autotask は、API トラッキング識別子ごと、エンドポイントごとに同時実行スレッドを 3 つに制限します。LLM が複数のツール呼び出しを同時に行うと（例：チケット、会社、連絡先を一度に検索する場合）、リクエストが積み重なり、この制限に達することがあります。

組み込みの緩和策：HTTP クライアントは、テナントごとの処理中リクエスト数を上限（AUTOTASK_MAX_INFLIGHT、デフォルトは 3）までに制限し、残りのリクエストをキューに入れます。そのため、並列リクエストが集中してもスレッドのしきい値に達することなく、空き枠ができるまで待機します。負荷が高いと応答が遅くなることがあります。冪等な呼び出しでスレッドしきい値による 429 が発生した場合は、短時間再試行されます。一方、1 時間あたりのリクエストしきい値に達した場合は、構造化されたレート制限エラーが返され、テナントは短時間クールダウン状態になります。

チーム／マルチユーザー環境で特に重要：複数のユーザーまたは MCP Gateway が同じ API 認証情報を共有している場合、同じ 3 スレッド分の予算を取り合います。その結果、目に見えて処理が遅くなったり、深刻な場合はキュー内のリクエストがタイムアウトしたりすることがあります。

解決策 — チームごとに 1 つの API キー：チームまたは連携ごとに専用の Autotask API ユーザーを作成します。各ユーザーには、それぞれ独立したスレッド予算を持つ integrationCode が割り当てられます。

1. Admin > Resources (Users) > Resources/Users → Add Resource
2. Security Level を API User に設定します
3. ユーザー名、シークレット、連携コードを控えます
4. チームごとに AUTOTASK_USERNAME、AUTOTASK_SECRET、AUTOTASK_INTEGRATION_CODE を設定します

Support Team  → AUTOTASK_INTEGRATION_CODE=SUPPORT_TEAM_CODE  (3 threads)
Projects Team → AUTOTASK_INTEGRATION_CODE=PROJECTS_TEAM_CODE (3 threads, independent)

また、Autotask は、テナントにリクエストを送信するすべての連携を合わせて、1 時間あたり合計 10,000 件のリクエストに制限しています。この上限に達すると、すべての連携で 429 が返されるようになります。適切なフィルターを使った対象を絞ったクエリを使用する理由はここにもあります。

MCP クライアントの問題

問題：Claude Desktop に MCP サーバーが表示されない 解決策：

1. 設定ファイルの構文を確認します（有効な JSON であること）
2. 設定内のファイルパスを確認します
3. 環境変数が正しく設定されていることを確認します
4. Claude Desktop を完全に再起動します

問題：「Invalid JSON-RPC message: [dotenv@...] injecting env」／サーバーが切断される 原因：autotask-node ライブラリは、モジュールの読み込み時に dotenv.config() を呼び出します。dotenv v17 以降は、ステータスメッセージを console.log 経由で stdout に出力するため、MCP stdio JSON-RPC チャネルが破損します。 解決策：エントリーポイントとして dist/index.js ではなく dist/entry.js を使用していることを確認してください。エントリーラッパーは、ライブラリが読み込まれる前に console.log を stderr にリダイレクトします。

問題：応答が遅い 解決策：

1. Autotask API へのネットワーク接続を確認します
2. デバッグログ（LOG_LEVEL=debug）を有効にして、ボトルネックを特定します
3. サーバーは会社名／リソース名を自動的に 30 分間キャッシュします

セキュリティのベストプラクティス

• 認証情報は設定ファイルに直接記述せず、環境変数に保存します
• Autotask API ユーザーの権限を必要最小限に制限します
• API 認証情報を定期的にローテーションします
• Docker のデプロイでは、プレーンな環境変数ではなくシークレット管理を使用します

コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

開発ガイドライン

• TypeScript のベストプラクティスに従います
• テストカバレッジを 80% 以上に維持します
• Conventional Commits のコミットメッセージを使用します
• API の変更に合わせてドキュメントを更新します
• 新機能のテストを追加します

ライセンス

このプロジェクトは Apache License 2.0 の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

コントリビューターライセンス契約

プルリクエストを送信することで、コントリビューターライセンス契約の条件に同意したものとみなされます。これにより、コントリビューションが適切にライセンスされ、コードを提出する権利があることが保証されます。

コントリビューター

アバター	名前	コントリビューション
	@asachs01	メンテナー
	@Baphomet480	CLI バイナリの修正

サポート

• 📚 ドキュメント
• 🐛 課題トラッカー
• 💬 ディスカッション

謝辞

• Anthropic による Model Context Protocol
• Kaseya による Autotask REST API
• autotask-node ライブラリ

---

WYRE Technology が開発 — MSP Claude Plugins エコシステムの一部