Autotask

Autotask MCP 服务

让 AI 助手直接访问 Autotask。 搜索工单、创建工时记录、查询公司、管理项目——通过自然语言即可完成。无需再在浏览器标签页和聊天窗口之间来回复制粘贴。

这是一个 Model Context Protocol (MCP) 服务，可将 Claude（或任何兼容 MCP 的 AI）连接到你的 Autotask PSA 环境。你的 AI 助手将获得 101 个工具，涵盖 MSP 团队日常使用的操作：工单分流、工时记录、公司查询、项目管理、账单审核等。

如果你在 Autotask 上运营 MSP，并且厌倦了频繁切换上下文，这就是为你准备的。

属于 MSP Claude Plugins 生态的一部分——这是一个不断扩展的 MSP 技术栈 AI 集成套件，包括 Datto RMM、IT Glue、HaloPSA、ConnectWise Automate、NinjaOne、Huntress 等。由 MSP 为 MSP 打造。

一键部署

注意——无需 GitHub Packages 令牌。 与大多数 WYRE MCP 服务不同， autotask-mcp 不依赖 GitHub Packages 上的私有 @wyre-ai/* 包。 它唯一的 WYRE 依赖是 autotask-node SDK，该依赖通过 git 指向公开的 WYRE-AI/autotask-node 仓库，npm install 可匿名解析。因此，DigitalOcean 一键部署 无需任何 NODE_AUTH_TOKEN/GITHUB_TOKEN 构建变量即可使用。

快速开始

Claude Desktop——下载、打开，即可使用：

1. 从最新版本下载 autotask-mcp.mcpb
2. 打开文件（双击，或将其拖入 Claude Desktop）
3. 根据提示输入 Autotask 凭据（用户名、密钥、集成代码）

无需终端、无需编辑 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）：在 MCP Apps 宿主（Claude Desktop/web）中，autotask_get_ticket_details 会呈现为交互式卡片，并支持在卡片内“添加备注”并往返传递；默认采用中性主题，可通过 MCP_BRAND_* 环境变量进行品牌定制。在所有宿主中，助手读取的文本都包含完整工单信息：描述、联系人、关联的配置项、自定义字段（UDF）、近期备注以及完整的 JSON 记录
• 🛠️ 全面的 API 覆盖：涵盖公司、联系人、工单、项目、计费项目、工时记录、备注、附件等的 101 个工具
• 🔍 高级搜索：提供强大的搜索功能，可按所有实体进行筛选
• 📝 CRUD 操作：创建、读取和更新核心 Autotask 实体
• 🔄 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），只需运行一条命令：

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

缺少三个 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 标头和三个 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 签名

如果 CONDUIT_S2S_SECRET 不是有效密钥，MCP_TRANSPORT=http 将拒绝启动。空值和已知占位符都会被拒绝，包括 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 是对 ASCII 字符串 t=<unix seconds>（即标头开头的同一个 t= 前缀）进行 HMAC-SHA256 运算后得到的十六进制编码值，密钥为 CONDUIT_S2S_SECRET。时间戳与服务器时钟的偏差必须在 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 模式下，还必须提供上述三个 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 - 列出工时记录

工具

该服务提供 101 个用于与 Autotask 交互的工具：

公司操作

• autotask_search_companies - 使用筛选条件搜索公司
• autotask_create_company - 创建公司
• autotask_update_company - 更新现有公司

联系人操作

• autotask_search_contacts - 使用筛选条件搜索联系人
• autotask_create_contact - 创建联系人

工单操作

• autotask_search_tickets - 使用筛选条件搜索工单
• autotask_get_ticket_details - 按 ID 获取工单详情：描述、状态／优先级／队列、公司、联系人、受派人、日期、关联的配置项、解决方案、自定义字段（UDF）、近期备注和完整记录（设置 fullDetails: true 可获取未截断的文本和全部 UDF）
• autotask_create_ticket - 创建工单

工时记录操作

• autotask_create_time_entry - 记录工时
• autotask_search_time_entries - 使用筛选条件搜索工时记录（资源、工单、任务、日期范围）；每条记录都包含 summaryNotes 和 internalNotes

计费项目（审批和过账工作流）

• 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 - 创建合同基本信息，可创建一个或多个
• 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 到名称映射

Autotask MCP 服务包含智能 ID 到名称映射功能，可自动将公司和资源 ID 转换为易于理解的名称，让 API 响应对 AI 助手和用户更有用。

自动增强

所有搜索和详情工具都会自动添加包含已解析名称的 _enhanced 字段：

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

工作原理

ID 到名称映射会自动应用于所有搜索和详情工具结果。无需使用其他工具——凡是包含公司或资源 ID 的响应，都会透明地添加 _enhanced 字段。

性能特性

• 智能缓存：名称缓存 30 分钟，以减少 API 调用
• 批量操作：高效批量查询多个 ID
• 优雅回退：查询失败时返回“Unknown Company (123)”
• 并行处理：同时解析多个映射

测试映射

测试映射功能：

npm run test:mapping

有关映射的详细文档，请参阅 docs/mapping.md。

HTTP 传输

该服务支持 MCP Streamable HTTP 传输，可用于远程部署（例如 Docker、云托管）。设置 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 规范，客户端必须向 /mcp 发送请求，并附带 Accept: application/json, text/event-stream 标头。

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

如需将 stdio 与 Claude Desktop 配合使用，请参阅安装选项 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，直到窗口滚动更新

由大模型驱动的工作流很容易发起大量并发请求——“汇总所有未结项目的状态并附上备注”可能会在几分钟内发起数百次请求。此服务采取了以下措施来降低风险：

• 429 响应会作为结构化错误返回。 工具结果包含 error_type: "rate_limited"，以及从 Autotask 的 Retry-After 标头解析出的 retry_after_seconds 字段。错误消息会明确告知大模型不要重试，并要求它请用户缩小查询范围，以避免反复重试延长冷却时间。
• 并发线程导致的 429 会排队处理，而不是冷却一分钟。 当集成超过线程阈值时，Autotask 也会返回 HTTP 429（响应正文中会提到“thread threshold”）。这是突发流量问题，与每小时配额不同。HTTP 客户端会限制每个租户同时执行的调用数量（默认值为 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）都包含提示，提醒大模型先缩小父记录列表范围，再逐项处理。

提高限制

可在 Autotask 中提高每个集成的阈值：

1. Autotask Admin → Resources/Users (HR) → Resources
2. 编辑专用 API 用户 → Workflow Rules → API Tracking Identifier
3. 调整 MCP 服务所用集成代码的阈值

如果 Claude、Copilot 等与其他工具共用同一个集成代码，这就是正确的解决方案。对于大模型密集型工作负载，请使用单独的 API 用户（和集成代码），避免一个客户端发出的扇出请求耗尽其他客户端的额度。

有用的模式

• 搜索备注、工时记录和附件时，始终限定日期范围。 即使是 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 会短暂重试；每小时请求阈值仍会以结构化的速率限制错误形式显示，并触发短暂的租户冷却期。

对团队/多用户部署至关重要：如果多个用户或 MCP Gateway 共用相同的 API 凭据，他们会竞争同一份 3 线程额度。这可能导致明显的速度下降，严重时还会出现排队请求超时。

解决方案 — 每个团队使用一个 API 密钥：为每个团队或集成创建专用的 Autotask API 用户。每个用户都有独立的 integrationCode 和线程额度：

1. Admin > Resources (Users) > Resources/Users → 添加资源
2. 将安全级别设为 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 会对访问你租户的所有集成实施每小时总计 10,000 个请求的限制。如果达到此限制，所有集成都将开始收到 429 错误；这也是使用带有适当筛选条件的定向查询的另一个原因。

MCP 客户端问题

问题：MCP 服务未显示在 Claude Desktop 中 解决方案：

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/entry.js（而非 dist/index.js）作为入口点。入口包装器会在加载任何库之前将 console.log 重定向到 stderr。

问题：响应缓慢 解决方案：

1. 检查与 Autotask API 的网络连接
2. 启用调试日志（LOG_LEVEL=debug）以定位瓶颈
3. 服务会自动缓存公司／资源名称 30 分钟

安全最佳实践

• 将凭据存储在环境变量中，而不是直接放在配置文件里
• 将 Autotask API 用户权限限制为所需的最低权限
• 定期轮换 API 凭据
• 对于 Docker 部署，请使用机密管理，而不是纯文本环境变量

贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到该分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

开发指南

• 遵循 TypeScript 最佳实践
• 保持测试覆盖率高于 80%
• 使用约定式提交消息
• API 变更时更新文档
• 为新功能添加测试

许可证

本项目根据 Apache License 2.0 授权。详情请参阅 LICENSE 文件。

贡献者许可协议

提交 Pull Request 即表示你同意我们的 贡献者许可协议 条款。这确保贡献内容能够得到适当授权，并且你有权提交这些代码。

贡献者

头像	姓名	贡献
	@asachs01	维护者
	@Baphomet480	修复 CLI 可执行文件

支持

• 📚 文档
• 🐛 问题跟踪器
• 💬 讨论区

致谢

• Anthropic 开发的 Model Context Protocol
• Kaseya 开发的 Autotask REST API
• autotask-node 库

---

由 WYRE Technology 构建——属于 MSP Claude Plugins 生态系统