使用说明

自动任务MCP服务器

让你的AI助手直接访问自动任务。 搜索门票、创建时间条目、查找公司、管理项目——所有这些都是通过自然语言完成的。不再在浏览器选项卡和聊天窗口之间进行复制粘贴。

这是一个模型上下文协议（MCP）将Claude（或任何兼容MCP的AI）连接到Autotask PSA环境的服务器。您的人工智能助手将获得39个工具，涵盖MSP团队每天使用的操作：工单分类、时间记录、公司查找、项目管理、账单审查等。

如果你在Autotask上运行MSP，并且厌倦了上下文切换税，那么这就是为你准备的。

部分 MSP克劳德插件生态系统 --MSP堆栈中不断增长的AI集成套件，包括 Datto RMM, IT胶水, Halopsa, ConnectWise自动化, NinjaOne, 女猎手以及更多。由MSP构建，适用于MSP。

一键部署

快速开始

克劳德桌面版 --下载、打开、完成：

下载 autotask-mcp.mcpb 从最新版本
打开文件（双击或拖动到Claude Desktop）
在系统提示时输入您的自动任务凭据（用户名、密码、集成代码）

无需终端，无需JSON编辑，无需安装Node.js。

克劳德代码（CLI）：

claude mcp add autotask-mcp \
  -e AUTOTASK_USERNAME=your-user@company.com \
  -e AUTOTASK_SECRET=your-secret \
  -e AUTOTASK_INTEGRATION_CODE=your-code \
  -- npx -y github:wyre-technology/autotask-mcp

看安装 Docker和源代码方法。

特性

🔌 MCP协议合规性：完全支持MCP资源和工具
🛠️ API全面覆盖：39个工具，涵盖公司、联系人、工单、项目、计费项目、时间条目、笔记、附件等
🔍 高级搜索：强大的搜索功能，可过滤所有实体
📝 CRUD操作：为核心自动任务实体创建、读取和更新操作
🔄 ID到名称映射：自动将公司和资源ID解析为人类可读的名称
⚡ 智能高速缓存：用于提高性能和减少API调用的智能缓存系统
🔒 安全认证：具有Autotask凭据的企业级API安全性
🌐 双重运输：支持stdio（本地）和HTTP流式传输（远程/Docker）
📦 MCPB包装：桌面客户端通过MCP Bundle一键安装
🐳 Docker就绪：具有HTTP传输和健康检查的容器化部署
📊 结构化日志：具有可配置级别和格式的全面日志记录
🧪 测试覆盖率：全面的测试套件，覆盖率超过80%

安装

选项1:MCPB捆绑包（克劳德桌面版）

最简单的方法——无需终端，无需JSON编辑，无需安装Node.js。

下载 autotask-mcp.mcpb 从最新版本
打开文件（双击或拖动到Claude Desktop）
在系统提示时输入您的自动任务凭据（用户名、密码、集成代码）

对于 克劳德代码（CLI），一个命令：

claude mcp add autotask-mcp \
  -e AUTOTASK_USERNAME=your-user@company.com \
  -e AUTOTASK_SECRET=your-secret \
  -e AUTOTASK_INTEGRATION_CODE=your-code \
  -- npx -y github:wyre-technology/autotask-mcp

选项2:Docker

本地（stdio——用于克劳德桌面或克劳德代码）：

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

远程（HTTP流式传输-用于服务器部署）：

docker run -d \
  --name autotask-mcp \
  -p 8080:8080 \
  -e AUTOTASK_USERNAME="your-user@company.com" \
  -e AUTOTASK_SECRET="your-secret" \
  -e AUTOTASK_INTEGRATION_CODE="your-code" \
  --restart unless-stopped \
  ghcr.io/wyre-technology/autotask-mcp:latest

# Verify
curl http://localhost:8080/health

客户端连接到 http://host:8080/mcp 使用MCP流式HTTP传输。

网关模式（用于MCP网关部署）：

当部署在通过HTTP标头注入凭据的MCP网关后面时：

docker run -d \
  --name autotask-mcp \
  -p 8080:8080 \
  -e AUTH_MODE=gateway \
  --restart unless-stopped \
  ghcr.io/wyre-technology/autotask-mcp:latest

网关通过标头注入凭据：

X-API-Key：自动任务用户名
X-API-Secret：自动任务机密
X-Integration-Code：自动任务集成代码

看网关模式了解详情。

选项3：来源（开发）

git clone https://github.com/wyre-technology/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": "your-user@company.com",
        "AUTOTASK_SECRET": "your-secret",
        "AUTOTASK_INTEGRATION_CODE": "your-code"
      }
    }
  }
}

先决条件

有效的Autotask API凭证（API用户电子邮件、机密、集成代码）
MCP兼容客户端（克劳德桌面、克劳德代码等）
Docker（用于选项2）或Node.js 18+（用于选项3）

配置

环境变量

创建一个 .env 使用您的配置文件：

# Required Autotask API credentials (Local Mode)
AUTOTASK_USERNAME=your-api-user@example.com
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)

# 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)
MCP_HTTP_HOST=0.0.0.0        # HTTP transport bind address

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

# Environment
NODE_ENV=production

网关模式

当部署在MCP网关后面时（例如。， mcp.wyre.ai)，服务器在网关模式下运行，在该模式下，凭据通过HTTP标头在每个请求上注入。

启用网关模式：

AUTH_MODE=gateway
MCP_TRANSPORT=http

预期标题：

标题	描述
`X-API-Key`	自动任务API用户名（电子邮件）
`X-API-Secret`	自动任务API密钥
`X-Integration-Code`	自动任务集成代码
`X-API-URL`	（可选）自定义自动任务API URL

健康检查响应（网关模式）：

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

有关详细的迁移说明，请参阅迁移指南.

💡 专业提示：将上述内容复制到 .env 项目根目录中的文件。

自动任务API设置

创建API用户：在Autotask中，创建具有适当权限的专用API用户
生成密钥：为用户生成API机密
集成代码：从Autotask获取集成代码
权限：确保API用户具有对所需实体的读/写访问权限

有关详细的设置说明，请参阅 Autotask API文档.

用法

命令行

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

# Start with HTTP transport
MCP_TRANSPORT=http node dist/index.js

MCP客户端配置

看安装对于所有设置方法。

API 参考

资源

资源提供对自动任务数据的只读访问：

autotask://companies -列出所有公司
autotask://companies/{id} -获取特定公司
autotask://contacts -列出所有联系人
autotask://contacts/{id} -获取具体联系方式
autotask://tickets -列出所有门票
autotask://tickets/{id} -获取特定票
autotask://time-entries -列出时间条目

工具

服务器提供39个与自动任务交互的工具：

公司运营

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_expense_report / autotask_search_expense_reports / autotask_create_expense_report
autotask_get_quote / autotask_search_quotes / autotask_create_quote
autotask_search_invoices -搜索发票
autotask_search_contracts -搜索合同

配置项目

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响应对人工智能助手和人工用户更有用。

自动增强

所有搜索和详细信息工具都自动包含 _enhanced 具有解析名称的字段：

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

运作原理

ID到名称的映射会自动应用于所有搜索和详细信息工具结果。不需要额外的工具—— _enhanced 字段透明地添加到包含公司或资源ID的每个响应中。

性能特点

智能缓存：缓存名称30分钟以减少API调用
批量操作：高效地批量查找多个ID
优雅的后退：如果查找失败，则返回“未知公司（123）”
并行处理：同时解析多个映射

测试映射

测试映射功能：

npm run test:mapping

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

HTTP传输

服务器支持用于远程部署的MCP Streamable HTTP传输（例如Docker、云托管）。集 MCP_TRANSPORT=http 以启用它。

# Start with HTTP transport
MCP_TRANSPORT=http MCP_HTTP_PORT=8080 node dist/index.js

HTTP传输公开了：

POST /mcp --MCP可流式HTTP端点
GET /health --健康检查（退货 {"status":"ok"})

客户端必须向发送请求 /mcp 随着 Accept: application/json, text/event-stream 根据MCP Streamable HTTP规范的标头。

Docker部署

Docker镜像默认使用HTTP传输（端口8080），并内置健康检查。

使用GitHub容器注册表中的预构建映像

Docker镜像默认为 HTTP传输 在端口8080上——适用于客户端通过网络连接的远程/服务器部署。

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

# Run container with HTTP transport (default)
docker run -d \
  --name autotask-mcp \
  -p 8080:8080 \
  -e AUTOTASK_USERNAME="your-api-user@example.com" \
  -e AUTOTASK_SECRET="your-secret-key" \
  -e AUTOTASK_INTEGRATION_CODE="your-integration-code" \
  --restart unless-stopped \
  ghcr.io/wyre-technology/autotask-mcp:latest

# Verify it's running
curl http://localhost:8080/health

对于标准使用Claude Desktop时，请参阅安装选项2.

快速入门（来源）

# Clone repository
git clone https://github.com/wyre-technology/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-technology/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`	✅	-	自动任务API用户名（电子邮件）
`AUTOTASK_SECRET`	✅	-	自动任务API密钥
`AUTOTASK_INTEGRATION_CODE`	✅	-	自动任务集成代码
`AUTOTASK_API_URL`	❌	自动检测	自动任务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`	HTTP传输绑定地址
`LOG_LEVEL`	❌	`info`	日志记录级别
`LOG_FORMAT`	❌	`simple`	日志输出格式
`NODE_ENV`	❌	`development`	Node.js环境

日志记录级别

error：只有错误消息
warn：警告和错误
info：一般信息、警告和错误
debug：详细的调试信息

日志格式

simple：人类可读的控制台输出
json：结构化JSON输出（建议用于生产）

故障排除

常见问题

身份验证错误

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费率限制

问题: 429 Too Many Requests 或者当Claude积极查询时出现“超出线程限制”错误

自动任务强制执行 每个API跟踪标识符每个端点3个并发线程当LLM同时发出多个工具调用时（例如，同时搜索工单、公司和联系人），请求可能会堆积并达到此限制。

内置缓解措施：基础 autotask-node SDK会自动将多余的请求排队，而不是立即失败。请求等待一个插槽释放，因此您通常不会看到429个错误，但您可能会注意到在重负载下响应较慢。

对于团队/多用户部署至关重要：如果多个用户或MCP网关共享 相同的API凭据，他们争夺相同的3线程预算。这可能会导致明显的速度减慢，在严重的情况下，还会导致排队的请求超时。

解决方案-每个团队一个API密钥：为每个团队或集成创建一个专用的Autotask API用户。每个用户都有一个独立的 integrationCode 有自己的线程预算：

管理员>资源（用户）>资源/用户 → 添加资源
将安全级别设置为 API用户
注意用户名、密码和集成代码
集 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)

此外，自动任务限制 每小时共有10000个请求 在所有影响租户的集成中。如果达到此限制，所有集成都将开始收到429，这是使用具有适当过滤器的目标查询的另一个原因。

MCP客户端问题

问题：MCP服务器未出现在Claude Desktop中 解决方案:

检查配置文件语法（有效的JSON）
验证配置中的文件路径
确保环境变量设置正确
完全重新启动克劳德桌面

问题：“JSON-RPC消息无效：[dotenv@...]注入env“/服务器已断开连接原因：The autotask-node 库调用 dotenv.config() 在模块加载时。dotenv v17+通过以下方式写入状态消息 console.log 这会损坏MCP stdio JSON-RPC通道。 解决方案：确保您正在使用 dist/entry.js （不是 dist/index.js)作为切入点。入口包装重定向 console.log 在加载任何库之前，请先将stderr。

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

检查Autotask API的网络连接
启用调试日志记录(LOG_LEVEL=debug)识别瓶颈
服务器自动缓存公司/资源名称30分钟

安全最佳实践

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

贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

开发指南

遵循TypeScript的最佳实践
保持测试覆盖率在80%以上
使用常规提交消息
更新API变更文档
为新功能添加测试

许可证

该项目根据 Apache许可证2.0。请参阅许可证文件以获取详细信息。

贡献者许可协议

提交pull请求即表示您同意我们的条款贡献者许可协议。这确保了贡献可以得到适当的许可，并且您有权提交代码。

贡献者

头像	名称	贡献
	@asachs01	维护人员
	@巴普米特480	CLI bin修复

支持

📚 文档
🐛 问题追踪器
💬 讨论

致谢

模型上下文协议通过Anthropic
自动任务REST API 通过Kaseya
自动任务节点图书馆

由...建造 WYRE技术 --部分 MSP克劳德插件生态系统

使用说明

自动任务MCP服务器

一键部署

快速开始

特性

目录

安装

选项1:MCPB捆绑包（克劳德桌面版）

选项2:Docker

选项3：来源（开发）

先决条件

配置

环境变量

网关模式

自动任务API设置

用法

命令行

MCP客户端配置

API 参考

资源

工具

公司运营

联系运营

票务操作

时间输入操作

计费项目（审批和发布工作流）

项目运营

资源操作

注释操作

附件操作

财务运营

配置项目

任务操作

公用事业运营

工具使用示例

ID到名称映射

自动增强

运作原理

性能特点

测试映射

HTTP传输

Docker部署

使用GitHub容器注册表中的预构建映像

快速入门（来源）

生产部署

开发模式

发展

设置

可用脚本

项目结构

测试

运行测试

测试类别

覆盖范围要求

配置参考

环境变量

日志记录级别

日志格式

故障排除

常见问题

身份验证错误

连接超时

权限不足

调试模式

健康检查

Autotask API费率限制

MCP客户端问题

安全最佳实践

贡献

开发指南

许可证

贡献者许可协议

贡献者

支持

致谢

相关 MCP

网页搜索MCP服务器

Zotero文献库搜索与阅读MCP服务

Prometheus 指标查询 MCP 服务器

SSH远程命令执行MCP服务器