Autotask

io.github.WYRE-AI由 GitHub 帳號 WYRE-AI 發布v2.44.1更新於 Nov 21, 2026

MCP server for Kaseya Autotask PSA — companies, tickets, projects, time entries, and more.

已驗證STDIO僅桌面效率與工作流商業與電商

概覽

AI 產生的概覽

針對 Kaseya Autotask PSA 的 MCP 伺服器,讓助理搜尋、讀取並建立公司、工單、專案、工時、合約與計費記錄。

可以做什麼
  • 搜尋與讀取公司、聯絡人、資源及設定項目,並把 ID 轉成可讀名稱
  • 搜尋、讀取與建立工單,包含含備註、自訂欄位與附件的完整工單內容
  • 搜尋、建立與更新專案、任務、合約及合約服務項目,並記錄或搜尋工時
  • 搜尋與讀取計費項目與簽核層級,並搜尋發票
  • 讀取與建立工單、專案、公司備註,以及費用報告、報價與商機
適用情境
適合讓助理在託管服務或專業服務的 PSA 中作業:查詢客戶工單、草擬或登記工單與工時、檢查合約續約,或檢視計費與報價資料,而不必切換到 Autotask 網頁介面。
執行需求
以本機程序(stdio)執行,可透過 MCP 安裝包、npx、Docker 映像,或以 Node.js 18+ 從原始碼建置。需要 Autotask API 憑證:AUTOTASK_USERNAME、AUTOTASK_SECRET 與 AUTOTASK_INTEGRATION_CODE;AUTOTASK_API_URL 會自動偵測。HTTP 模式另需 CONDUIT_S2S_SECRET 與 X-Gateway-S2S 簽章,或改用閘道模式由請求標頭帶入憑證。
安裝前請注意
需要真實的 Autotask API 使用者密鑰與整合代碼,可讀寫租戶資料。許多工具會建立或更新記錄(工單、備註、工時、合約、報價、商機),助理的操作會改動真實業務資料。選用的模擬身分功能會把寫入歸屬到其他資源,取決於租戶安全層級設定。HTTP 模式需要真實的服務間密鑰;不安全開發開關會關閉此檢查。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Autotask,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Autotask MCP Server

[Build Status] [codecov] [License] [Node.js]

Give your AI assistant direct access to Autotask. Search tickets, create time entries, look up companies, manage projects — all through natural language. No more copy-pasting between browser tabs and chat windows.

This is a Model Context Protocol (MCP) server that connects Claude (or any MCP-compatible AI) to your Autotask PSA environment. Your AI assistant gets 102 tools covering the operations MSP teams use daily: ticket triage, time logging, company lookups, project management, billing review, and more.

If you run an MSP on Autotask and you're tired of the context-switching tax, this is for you.

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

[Autotask MCP server]

One-Click Deployment

[Deploy to DO]

[Deploy to Cloudflare Workers]

Note — no GitHub Packages token required. Unlike most WYRE MCP servers, autotask-mcp does not depend on a private @wyre-ai/* package on GitHub Packages. Its only WYRE dependency is the autotask-node SDK, declared as a git dependency on the public WYRE-AI/autotask-node repo, which npm install resolves anonymously. The DigitalOcean one-click deploy therefore works without any NODE_AUTH_TOKEN/GITHUB_TOKEN build variable.

Quick Start

Claude Desktop — download, open, done:

  1. Download autotask-mcp.mcpb from the latest release
  2. Open the file (double-click or drag into Claude Desktop)
  3. Enter your Autotask credentials when prompted (Username, Secret, Integration Code)

No terminal, no JSON editing, no Node.js install required.

Claude Code (CLI):

bash
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

See Installation for Docker and from-source methods.

Features

  • 🔌 MCP Protocol Compliance: Full support for MCP resources and tools
  • 🎴 Interactive Ticket Card (MCP Apps): autotask_get_ticket_details renders as an interactive card in MCP Apps hosts (Claude Desktop/web) with an in-card "Add note" round-trip; neutral theme by default, brandable via MCP_BRAND_* env vars. In every host, the text the assistant reads carries the full ticket: description, contact, linked configuration item, custom fields (UDFs), recent notes and the complete record as JSON
  • 🛠️ Comprehensive API Coverage: 102 tools spanning companies, contacts, tickets, projects, billing items, time entries, notes, attachments, and more
  • 🔍 Advanced Search: Powerful search capabilities with filters across all entities
  • 📝 CRUD Operations: Create, read, update operations for core Autotask entities
  • 🔄 ID-to-Name Mapping: Automatic resolution of company and resource IDs to human-readable names
  • ⚡ Intelligent Caching: Smart caching system for improved performance and reduced API calls
  • 🔒 Secure Authentication: Enterprise-grade API security with Autotask credentials
  • 🌐 Dual Transport: Supports both stdio (local) and HTTP Streamable (remote/Docker) transports
  • 📦 MCPB Packaging: One-click installation via MCP Bundle for desktop clients
  • 🐳 Docker Ready: Containerized deployment with HTTP transport and health checks
  • 📊 Structured Logging: Comprehensive logging with configurable levels and formats
  • 🧪 Test Coverage: Comprehensive test suite with 80%+ coverage

Table of Contents

Installation

Option 1: MCPB Bundle (Claude Desktop)

The simplest method — no terminal, no JSON editing, no Node.js install required.

  1. Download autotask-mcp.mcpb from the latest release
  2. Open the file (double-click or drag into Claude Desktop)
  3. Enter your Autotask credentials when prompted (Username, Secret, Integration Code)

For Claude Code (CLI), one command:

bash
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

Option 2: Docker

Local (stdio — for Claude Desktop or Claude Code):

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

Remote (HTTP Streamable — for server deployments):

bash
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

The HTTP server refuses to start when CONDUIT_S2S_SECRET is empty or a known placeholder. Clients connect to http://127.0.0.1:8080/mcp using MCP Streamable HTTP transport and must send X-Gateway-S2S. See X-Gateway-S2S signing.

Gateway Mode (for MCP Gateway deployments):

When deploying behind an MCP Gateway that injects credentials via HTTP headers. This container has no static Autotask credentials:

bash
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

The gateway injects credentials via headers:

  • X-Gateway-S2S: service-to-service proof (required on /mcp)
  • X-API-Key: Autotask username
  • X-API-Secret: Autotask secret
  • X-Integration-Code: Autotask integration code
  • X-Impersonation-Resource-Id: (optional) Autotask resource ID to act on behalf of

A /mcp request missing any of the three Autotask headers returns 401 and does not fall back to AUTOTASK_* in the environment. See Gateway Mode for details.

Option 3: From Source (Development)

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

Then point your MCP client at dist/entry.js:

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

Prerequisites

  • Valid Autotask API credentials (API user email, secret, integration code)
  • MCP-compatible client (Claude Desktop, Claude Code, etc.)
  • Docker (for Option 2) or Node.js 18+ (for Option 3)

Configuration

Environment Variables

Create a .env file with your configuration:

bash
# Required Autotask API credentials (Local Mode)[email protected]AUTOTASK_SECRET=your-secret-keyAUTOTASK_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/# Attribute notes and other supported writes to this Autotask resource (env mode)# AUTOTASK_IMPERSONATION_RESOURCE_ID=29682886MCP_SERVER_NAME=autotask-mcp
# Authentication modeAUTH_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, httpMCP_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
# LoggingLOG_LEVEL=info          # error, warn, info, debugLOG_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
# EnvironmentNODE_ENV=production

Gateway Mode

When deployed behind an MCP Gateway (e.g., mcp.wyre.ai), the server operates in gateway mode where credentials are injected via HTTP headers on each request.

Enable Gateway Mode:

bash
AUTH_MODE=gatewayMCP_TRANSPORT=httpCONDUIT_S2S_SECRET=<gateway-provisioned secret>

Every /mcp request must include a valid X-Gateway-S2S header and the three Autotask credential headers. A request missing any credential header returns 401. The server does not fall back to AUTOTASK_USERNAME, AUTOTASK_SECRET, or AUTOTASK_INTEGRATION_CODE in the process environment.

Expected Headers:

HeaderDescription
X-Gateway-S2SService-to-service proof. t=<unix seconds>,v1=<hex hmac-sha256>. Required on /mcp whenever CONDUIT_S2S_SECRET is set. See X-Gateway-S2S signing.
X-API-KeyAutotask API username (email)
X-API-SecretAutotask API secret key
X-Integration-CodeAutotask integration code
X-API-URL(Optional) Custom Autotask API URL
X-Conduit-Acting-User-Email(Optional) Verified email of the Conduit user making the call. Honored only on Node HTTP with a usable CONDUIT_S2S_SECRET (so only after X-Gateway-S2S verifies), never on the Cloudflare Worker. Writes impersonate the single active Autotask resource with that exact email; see Acting-user impersonation. Ignored when X-Impersonation-Resource-Id is present.
X-Autotask-Impersonate-Acting-User(Optional) on (or true/1) opts this connection in to acting-user impersonation. Conduit sends it from the Autotask connection's "Post writes as the signed-in person" setting. Honored only after X-Gateway-S2S verifies. Absent or anything else means writes run as the API user (unless AUTOTASK_IMPERSONATE_ACTING_USER is set).
X-Impersonation-Resource-Id(Optional) Autotask resource ID to act on behalf of. Forwarded to Autotask as its ImpersonationResourceId header, so actions are attributed to that resource instead of the API user, and recorded in the entity's read-only impersonatorCreatorResourceID field. Must be a positive integer; anything else is ignored with a warning. The impersonated resource must itself have permission for the action, and the API user's security level must permit impersonation.

Impersonation

Autotask attributes writes to another resource when a request carries the ImpersonationResourceId header. The server sends it on every Autotask call when a resource is set; Autotask applies it only to entities and actions that support impersonation and ignores it elsewhere. The supported list (see Entities that support impersonation) includes the note entities this server writes (TicketNote, ProjectNote, CompanyNote), plus TimeEntry, Ticket, Projects, Company, Contact, ServiceCall, Opportunity and Quote. Autotask records the impersonated resource as the creator and fills the read-only impersonatorCreatorResourceID; setting that field in a body does nothing.

Autotask's requirements:

  • The API-only user's security level must allow impersonation on the entity type.
  • The impersonated resource's security level must allow it to be impersonated ("Allow impersonation of resources with this security level").
  • Both must have permission to add or edit the entity.

Where the resource ID comes from:

ModeSourceFallback
AUTH_MODE=gatewayX-Impersonation-Resource-Id on that requestNone. Resource IDs are tenant-specific, so an env default is never applied to gateway requests.
AUTH_MODE=env, HTTPX-Impersonation-Resource-Id on that requestAUTOTASK_IMPERSONATION_RESOURCE_ID
AUTH_MODE=env, Cloudflare WorkerAUTOTASK_IMPERSONATION_RESOURCE_ID onlyNone. The Worker route has no X-Gateway-S2S check, so a caller-supplied header is not honored there.
AUTH_MODE=env, stdioAUTOTASK_IMPERSONATION_RESOURCE_IDNone

A per-request value builds a fresh service for that request only, so it never carries over to another request. Values that aren't positive integers are ignored with a warning. If Autotask rejects an impersonated call, the error says which resource was being impersonated and the call is not retried as the API user.

Acting-user impersonation

Default off. Note on v2.40.0: v2.40.0 turned acting-user impersonation on for every gateway request. On tenants whose Autotask API user isn't allowed to impersonate, every ticket note then failed with HTTP 500 "The logged in Resource does not have the adequate permissions to create this entity type.", and that response wasn't retried. v2.41.1 made the feature opt-in and retries that 500 once as the API user, and v2.42.0 added the per-connection opt-in header. Don't run v2.40.0.

Ways to impersonate, from highest precedence:

SourceScopeBehavior on refusal
Explicit resource ID: X-Impersonation-Resource-Id header, or AUTOTASK_IMPERSONATION_RESOURCE_ID in env mode (see Impersonation)Every call on that request or serverStrict: the call fails, and is never retried as the API user
Acting-user email (X-Conduit-Acting-User-Email), when opted in with X-Autotask-Impersonate-Acting-User: on for the connection, or AUTOTASK_IMPERSONATE_ACTING_USER=true for every tenantWrites onlyBest-effort: falls back to the API user as described below
NeitherEvery call runs as the API user (the default)

Opt-in: this is off unless the sidecar runs with AUTOTASK_IMPERSONATE_ACTING_USER=true (or 1) for every tenant, or the request carries X-Autotask-Impersonate-Acting-User: on (also true/1) for that connection. Conduit sets that header from the Autotask connection's "Post writes as the signed-in person" setting. Both are honored only after X-Gateway-S2S verifies. When off, the email header is ignored and writes run as the tenant's API user.

In gateway mode, Conduit sends the acting user's verified email in X-Conduit-Acting-User-Email, and the sidecar attributes that person's writes to their own Autotask resource:

  1. On the first write of a request (POST create, PATCH, PUT or DELETE; never a GET or a /query read), the sidecar queries active Resources by email with the tenant's own API credentials, as the API user.

  2. Exactly one active resource with that exact email (case-insensitive) is a match. The write carries ImpersonationResourceId: <id>.

  3. No match, more than one active match, or only inactive matches mean the write runs as the API user, as it did before.

  4. If Autotask refuses the impersonation, attribution for that user and operation (method and entity route) is switched off for 6 hours (AUTOTASK_IMPERSONATION_REJECTED_TTL_MS). Other operations keep impersonating. What happens to the refused write depends on the response:

    • A 403, or another 4xx (except 429) that mentions impersonation: the write is retried once as the API user. A rejected 4xx request was not applied, so the retry can't double-write.
    • A structured 500 saying the logged-in resource "does not have the adequate permissions to create this entity type": the write is retried once as the API user. This is Autotask's permission check, so nothing was written. It's what Autotask returns when the API user's security level doesn't allow impersonation (see the v2.40.0 note below).
    • Any other 500 whose structured errors list mentions impersonation: the write is not retried, because Autotask doesn't guarantee that a 500 wasn't applied. The call fails with a hint, and the next attempt runs as the API user.
    • Gateway 5xx responses and unstructured 500s are not treated as refusals at all.

    Usually a refusal means the tenant hasn't enabled impersonation in the security levels (see Impersonation).

Lookups are cached per tenant (API username) and email: matches for 15 minutes, misses for 5 minutes, lookup errors for 1 minute. You can tune this with AUTOTASK_IMPERSONATION_CACHE_TTL_MS and AUTOTASK_IMPERSONATION_MISS_TTL_MS. Cache keys are SHA-256 hashes, so raw emails are never stored. Lookup outcomes are logged at debug level, without the email.

Both headers (X-Conduit-Acting-User-Email and X-Autotask-Impersonate-Acting-User) are trusted only because Conduit is the only caller that can pass X-Gateway-S2S. Conduit sets the email from the user's verified login and the opt-in from the connection's stored setting, and strips any client-supplied copy. The sidecar ignores it on the Cloudflare Worker (no S2S check) and on an insecure-dev listener. An explicit X-Impersonation-Resource-Id always wins and keeps its strict behavior: it applies to every call, and a rejection fails the call.

X-Gateway-S2S signing

MCP_TRANSPORT=http refuses to start unless CONDUIT_S2S_SECRET is a real secret. Empty values and known placeholders are rejected, including changeme, placeholder, your-s2s-secret, secret, password, test, and any value that is only an unresolved ${...} template. The process logs an error and exits non-zero. It never prints the secret.

MCP_ALLOW_INSECURE_DEV=1 is the local-only escape hatch. The process logs a warning, does not check X-Gateway-S2S, and listens on 127.0.0.1 only. A non-loopback MCP_HTTP_HOST (including 0.0.0.0, localhost, and ::1) is ignored in that mode and the override is logged.

Without a usable secret the bind address defaults to 127.0.0.1. A configured secret honors MCP_HTTP_HOST (default 0.0.0.0 when that variable is unset, which is what the container image sets). Publish the host port on loopback unless a proxy sits in front.

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

With a usable secret, every /mcp request must include:

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

v1 is HMAC-SHA256, hex-encoded, of the ASCII string t=<unix seconds> (the same t= prefix that starts the header), keyed with CONDUIT_S2S_SECRET. The timestamp must be within 300 seconds of the server clock. A missing or invalid header returns HTTP 401. The secret is never written to logs or the response body.

bash
# 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"}'

In AUTH_MODE=env, /mcp still requires a valid X-Gateway-S2S header. Autotask credentials then come from AUTOTASK_*. In AUTH_MODE=gateway, the three X-API-* headers above are required as well and are the only credential source for that request.

Health Check Response (Gateway Mode):

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

For detailed migration instructions, see the Migration Guide.

💡 Pro Tip: Copy the above content to a .env file in your project root.

Autotask API Setup

  1. Create API User: In Autotask, create a dedicated API user with appropriate permissions
  2. Generate Secret: Generate an API secret for the user
  3. Integration Code: Obtain your integration code from Autotask
  4. Permissions: Ensure the API user has read/write access to required entities

For detailed setup instructions, see the Autotask API documentation.

Usage

Command Line

bash
# 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 secretCONDUIT_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 Client Configuration

See Installation for all setup methods.

API Reference

Resources

Resources provide read-only access to Autotask data:

  • autotask://companies - List all companies
  • autotask://companies/{id} - Get specific company
  • autotask://contacts - List all contacts
  • autotask://contacts/{id} - Get specific contact
  • autotask://tickets - List all tickets
  • autotask://tickets/{id} - Get specific ticket
  • autotask://time-entries - List time entries

Tools

The server provides 102 tools for interacting with Autotask:

Company Operations
  • autotask_search_companies - Search companies with filters
  • autotask_get_company - Get one company by ID with all fields and picklist labels (classification, type)
  • autotask_create_company - Create new company
  • autotask_update_company - Update existing company
Contact Operations
  • autotask_search_contacts - Search contacts with filters
  • autotask_create_contact - Create new contact
Ticket Operations
  • autotask_search_tickets - Search tickets with filters
  • autotask_get_ticket_details - Get a ticket by ID: description, status/priority/queue, company, contact, assignee, dates, linked configuration item, resolution, custom fields (UDFs), recent notes and the full record (fullDetails: true for untruncated text and all UDFs)
  • autotask_create_ticket - Create new ticket
Time Entry Operations
  • autotask_create_time_entry - Log time entry
  • autotask_search_time_entries - Search time entries with filters (resource, ticket, task, date range); each entry includes summaryNotes and internalNotes
Billing Items (Approve and Post Workflow)
  • autotask_search_billing_items - Search approved and posted billing items
  • autotask_get_billing_item - Get specific billing item by ID
  • autotask_search_billing_item_approval_levels - Search multi-level approval records for time entries
Project Operations
  • autotask_search_projects - Search projects with filters
  • autotask_create_project - Create new project
Resource Operations
  • autotask_search_resources - Search resources (technicians/users)
Note Operations
  • 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
Attachment Operations
  • autotask_get_ticket_attachment - Get ticket attachment
  • autotask_search_ticket_attachments - Search ticket attachments
  • autotask_get_ticket_note_attachment - Get an attachment on a ticket note (e.g. a pasted screenshot)
  • autotask_search_ticket_note_attachments - Search attachments on a ticket note
Financial Operations
  • 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 - Update an opportunity (stage, status, revenue/cost lines, UDFs)
  • autotask_search_invoices - Search invoices
Contract Operations
  • autotask_search_contracts - Search contracts (name, company, status, type, end-date range)
  • autotask_get_contract - Get a single contract by ID
  • autotask_list_expiring_contracts - Expiring/expired contracts report (next N days, per company or org-wide)
  • autotask_create_contract / autotask_create_contracts_bulk - Create contract shells, one or many
  • autotask_update_contract - Update a contract (e.g. extend/renew end date)
  • autotask_create_contract_service / autotask_update_contract_service - Manage contract service lines
Configuration Items
  • autotask_search_configuration_items - Search configuration items (assets)
Task Operations
  • autotask_search_tasks - Search project tasks
  • autotask_create_task - Create project task
Utility Operations
  • autotask_test_connection - Test API connectivity

Example Tool Usage

javascript
// 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 Mapping

The Autotask MCP server includes intelligent ID-to-name mapping that automatically resolves company and resource IDs to human-readable names, making API responses much more useful for AI assistants and human users.

Automatic Enhancement

All search and detail tools automatically include an _enhanced field with resolved names:

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

How It Works

ID-to-name mapping is applied automatically to all search and detail tool results. No additional tools are needed — the _enhanced field is added transparently to every response that contains company or resource IDs.

Performance Features

  • Smart Caching: Names are cached for 30 minutes to reduce API calls
  • Bulk Operations: Efficient batch lookups for multiple IDs
  • Graceful Fallback: Returns "Unknown Company (123)" if lookup fails
  • Parallel Processing: Multiple mappings resolved simultaneously

Testing Mapping

Test the mapping functionality:

bash
npm run test:mapping

For detailed mapping documentation, see docs/mapping.md.

HTTP Transport

The server supports the MCP Streamable HTTP transport for remote deployments (e.g., Docker, cloud hosting). Set MCP_TRANSPORT=http to enable it.

bash
# 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

The HTTP transport exposes:

  • POST /mcp — MCP Streamable HTTP endpoint. Requires X-Gateway-S2S when CONDUIT_S2S_SECRET is set. See X-Gateway-S2S signing.
  • GET /health — Unauthenticated health check (returns {"status":"ok"}). Does not read credentials.

Clients must send requests to /mcp with Accept: application/json, text/event-stream headers per the MCP Streamable HTTP specification.

Docker Deployment

The Docker image uses HTTP transport by default (port 8080) with a built-in health check.

Using Pre-built Image from GitHub Container Registry

The Docker image defaults to HTTP transport on port 8080 — suitable for remote/server deployments where clients connect over the network.

bash
# Pull the latest imagedocker 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

Compose will not start when CONDUIT_S2S_SECRET is unset. The checked-in gateway service sets AUTH_MODE=gateway, publishes 127.0.0.1:8080:8080, and does not inject AUTOTASK_*:

bash
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

For stdio usage with Claude Desktop, see Installation Option 2.

Quick Start (From Source)

bash
# Clone repositorygit clone https://github.com/WYRE-AI/autotask-mcp.gitcd autotask-mcp
# Create environment filecp .env.example .env# Edit .env with your credentials
# Start with docker-composedocker compose up -d

Production Deployment

bash
# Build production image locallydocker build -t autotask-mcp:latest .
# Run containerdocker run -d \  --name autotask-mcp \  --env-file .env \  --restart unless-stopped \  autotask-mcp:latest

Development Mode

bash
# Start development environment with hot reloaddocker compose --profile dev up autotask-mcp-dev

Development

Setup

bash
git clone https://github.com/WYRE-AI/autotask-mcp.gitcd autotask-mcpnpm install

Available Scripts

bash
npm run dev          # Start development server with hot reloadnpm run build        # Build for productionnpm run test         # Run test suitenpm run test:watch   # Run tests in watch modenpm run test:coverage # Run tests with coveragenpm run lint         # Run ESLintnpm run lint:fix     # Fix ESLint issues

Project Structure

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

Testing

Running Tests

bash
# Run all testsnpm test
# Run with coveragenpm run test:coverage
# Run in watch modenpm run test:watch
# Run specific test filenpm test -- tests/autotask-service.test.ts

Test Categories

  • Unit Tests: Service layer and utility functions
  • Integration Tests: MCP protocol compliance
  • API Tests: Autotask API integration (requires credentials)

Coverage Requirements

  • Minimum 80% coverage for all metrics
  • 100% coverage for critical paths (authentication, data handling)

Configuration Reference

Environment Variables

VariableRequiredDefaultDescription
AUTOTASK_USERNAME✅-Autotask API username (email)
AUTOTASK_SECRET✅-Autotask API secret key
AUTOTASK_INTEGRATION_CODE✅-Autotask integration code
AUTOTASK_API_URL❌Auto-detectedAutotask API endpoint URL
AUTOTASK_IMPERSONATE_ACTING_USER❌unset (off)Gateway mode. true or 1 turns on acting-user impersonation for every tenant. Leave it unset and opt in per connection with X-Autotask-Impersonate-Acting-User: on.
AUTOTASK_IMPERSONATION_CACHE_TTL_MS❌900000How long an acting-user email → resource match is cached (per tenant and email).
AUTOTASK_IMPERSONATION_MISS_TTL_MS❌300000How long a no-match, ambiguous or inactive lookup is cached.
AUTOTASK_IMPERSONATION_REJECTED_TTL_MS❌21600000How long acting-user impersonation stays off for a user and operation after Autotask refuses it.
AUTOTASK_IMPERSONATION_RESOURCE_ID❌unsetEnv mode only. Default Autotask resource ID to impersonate, sent as Autotask's ImpersonationResourceId header on every call so notes, time entries and other supported writes are attributed to that resource. Must be a positive integer; anything else is ignored with a warning. Over HTTP, a per-request X-Impersonation-Resource-Id header overrides it for that request only. Ignored in gateway mode, where each request supplies its own. See Impersonation.
MCP_SERVER_NAME❌autotask-mcpMCP server name
MCP_TRANSPORT❌stdioTransport type (stdio or http)
MCP_HTTP_PORT❌8080HTTP transport port
MCP_HTTP_HOST❌0.0.0.0 when a secret is set; 127.0.0.1 without oneHTTP bind address. A configured CONDUIT_S2S_SECRET honors this variable. MCP_ALLOW_INSECURE_DEV=1 forces 127.0.0.1.
CONDUIT_S2S_SECRETYes for HTTP—Service-to-service secret for X-Gateway-S2S. HTTP exits if this is empty or a known placeholder. Never commit a real value.
MCP_ALLOW_INSECURE_DEV❌unsetSet to exactly 1 for local HTTP without a usable secret. Logs a warning, skips X-Gateway-S2S, and listens on 127.0.0.1 only.
LOG_LEVEL❌infoLogging level
LOG_FORMAT❌simpleLog output format
AUTOTASK_ENHANCE_CONCURRENCY❌3Max concurrent Autotask API calls used to resolve company/resource names on search results. Kept low to stay under Autotask's concurrent-thread limit.
AUTOTASK_MAX_INFLIGHT❌3Max Autotask REST calls in flight per tenant. Further calls queue in the HTTP client instead of tripping the concurrent-thread limit.
NODE_ENV❌developmentNode.js environment

Logging Levels

  • error: Only error messages
  • warn: Warnings and errors
  • info: General information, warnings, and errors
  • debug: Detailed debugging information

Log Formats

  • simple: Human-readable console output
  • json: Structured JSON output (recommended for production)

Rate Limits

Autotask enforces per-integration-code API thresholds on a rolling 1-hour window:

  • ~10,000 req/hr (soft) — warning email, sporadic HTTP 429 responses
  • ~20,000 req/hr (hard) — sustained HTTP 429 until the window rolls

LLM-driven workflows fan out easily — "status report on all open projects with notes" can issue hundreds of requests across a few minutes. The server tries to make this safer:

  • 429 responses are surfaced as structured errors. Tool results carry error_type: "rate_limited" and a retry_after_seconds field parsed from Autotask's Retry-After header. The error message explicitly tells the LLM not to retry and to ask the user to scope the query — this prevents repeated retries from extending the cooldown.
  • Concurrent-thread 429s are queued, not cooled down for a minute. Autotask also returns HTTP 429 when an integration exceeds its thread threshold (the body mentions "thread threshold"). That is a burst problem, separate from the hourly quota. The HTTP client allows AUTOTASK_MAX_INFLIGHT calls in flight per tenant (default 3) and queues the rest. A thread-threshold 429 on an idempotent call (GET, DELETE, or POST /{Entity}/query) is retried with a short backoff and does not arm the 60s cooldown. Hourly-threshold 429s still arm it. Create/update calls are not retried automatically.
  • Fan-out tool descriptions include rate-limit tips. Tools that are commonly looped over (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) include a hint reminding the LLM to scope the parent record list before iterating.

Raising the limit

Per-integration thresholds can be increased in Autotask:

  1. Autotask Admin → Resources/Users (HR) → Resources
  2. Edit the dedicated API user → Workflow Rules → API Tracking Identifier
  3. Adjust the threshold for the integration code your MCP server uses

This is the right answer when a single integration code is shared between Claude/Copilot/etc. and other tooling. For LLM-heavy workloads, dedicate a separate API user (and integration code) so a fan-out from one client doesn't starve others.

Patterns that help

  • Always scope by date range when searching notes, time entries, attachments. Even a 30-day window can drop call count by an order of magnitude.
  • Cache parent lookups. If you're iterating over 100 tickets, fetch the ticket list once and reuse it across follow-up queries; don't re-search per child.
  • Use autotask_get_field_info to discover picklist values once per session rather than refetching them per call.

If you're seeing threshold warnings from Autotask but the server seems fine, the LLM driver is probably issuing fan-out patterns. Tighten the prompt to scope before iterating.

Troubleshooting

Common Issues

Authentication Errors
Error: Missing required Autotask credentials

Solution: Ensure all required environment variables are set correctly.

Connection Timeouts
Error: Connection to Autotask API failed

Solutions:

  • Check network connectivity
  • Verify API endpoint URL
  • Confirm API user has proper permissions
Permission Denied
Error: User does not have permission to access this resource

Solution: Review Autotask API user permissions and security level settings.

Debug Mode

Enable debug logging for detailed troubleshooting:

bash
LOG_LEVEL=debug npm start

Health Checks

Test server connectivity:

bash
# Run test suitenpm run test
# For HTTP transport, check the health endpointcurl http://localhost:8080/health# Returns: {"status":"ok"}
# Test API connection with debug loggingLOG_LEVEL=debug npm start

Autotask API Rate Limits

Problem: 429 Too Many Requests or "thread limit exceeded" errors when Claude queries aggressively

Autotask enforces 3 concurrent threads per endpoint per API tracking identifier. When an LLM issues multiple tool calls simultaneously (e.g., searching tickets, companies, and contacts at once), requests can pile up and hit this limit.

Built-in mitigation: The HTTP client caps in-flight requests per tenant (AUTOTASK_MAX_INFLIGHT, default 3) and queues the rest, so a parallel burst waits for a free slot instead of tripping the thread threshold. You may notice slower responses under heavy load. A thread-threshold 429 on an idempotent call is retried briefly; the hourly request threshold still surfaces as a structured rate-limit error and a short tenant cooldown.

Critical for team/multi-user deployments: If multiple users or the MCP Gateway share the same API credentials, they compete for the same 3-thread budget. This can cause noticeable slowdowns and, in severe cases, queued requests that time out.

Solution — one API key per team: Create a dedicated Autotask API user per team or integration. Each user has an independent integrationCode with its own thread budget:

  1. Admin > Resources (Users) > Resources/Users → Add Resource
  2. Set Security Level to API User
  3. Note the username, secret, and integration code
  4. Set AUTOTASK_USERNAME, AUTOTASK_SECRET, and AUTOTASK_INTEGRATION_CODE per team
Support Team  → AUTOTASK_INTEGRATION_CODE=SUPPORT_TEAM_CODE  (3 threads)Projects Team → AUTOTASK_INTEGRATION_CODE=PROJECTS_TEAM_CODE (3 threads, independent)

Additionally, Autotask limits 10,000 total requests per hour across all integrations hitting your tenant. If you hit this limit, all integrations will start receiving 429s — another reason to use targeted queries with appropriate filters.

MCP Client Issues

Problem: MCP server not appearing in Claude Desktop Solutions:

  1. Check configuration file syntax (valid JSON)
  2. Verify file path in the configuration
  3. Ensure environment variables are set correctly
  4. Restart Claude Desktop completely

Problem: "Invalid JSON-RPC message: [dotenv@...] injecting env" / Server disconnected Cause: The autotask-node library calls dotenv.config() at module load time. dotenv v17+ writes status messages via console.log to stdout, which corrupts the MCP stdio JSON-RPC channel. Solution: Ensure you're using dist/entry.js (not dist/index.js) as the entry point. The entry wrapper redirects console.log to stderr before any libraries load.

Problem: Slow responses Solutions:

  1. Check network connectivity to Autotask API
  2. Enable debug logging (LOG_LEVEL=debug) to identify bottlenecks
  3. The server caches company/resource names for 30 minutes automatically

Security Best Practices

  • Store credentials in environment variables, not directly in config files
  • Limit Autotask API user permissions to the minimum required
  • Rotate API credentials regularly
  • For Docker deployments, use secrets management rather than plain environment variables

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

Development Guidelines

  • Follow TypeScript best practices
  • Maintain test coverage above 80%
  • Use conventional commit messages
  • Update documentation for API changes
  • Add tests for new features

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

Contributor License Agreement

By submitting a pull request, you agree to the terms of our Contributor License Agreement. This ensures that contributions can be properly licensed and that you have the right to submit the code.

Contributors

AvatarNameContributions
[圖片]@asachs01Maintainer
[圖片]@Baphomet480CLI bin fix

Support

Acknowledgments


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

來源:README.md,提交 c52923d

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包,因此其工具未知。

版本歷史

19
  1. v2.44.1最新Nov 21, 2026
  2. v2.43.0Nov 19, 2026
  3. v2.42.0Nov 17, 2026
  4. v2.41.0Nov 16, 2026
  5. v2.40.0Nov 14, 2026
  6. v2.39.10Nov 14, 2026
  7. v2.39.9Nov 7, 2026
  8. v2.39.8Oct 21, 2026
  9. v2.39.7Oct 15, 2026
  10. v2.39.6Oct 14, 2026
  11. v2.39.5Oct 12, 2026
  12. v2.39.4Oct 9, 2026
  13. v2.39.3Oct 8, 2026
  14. v2.39.2Oct 5, 2026
  15. v2.39.0Oct 1, 2026
  16. v2.38.3Oct 1, 2026
  17. v2.38.2Sep 24, 2026
  18. v2.38.1Sep 20, 2026
  19. v2.38.0Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手;SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list,或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分