Autotask MCP Server
A Model Context Protocol (MCP) server that provides AI assistants with structured access to Kaseya Autotask PSA data and operations.
Quick Start
Claude Desktop — download, open, done:
- Download
autotask-mcp.mcpbfrom the latest release - Open the file (double-click or drag into Claude Desktop)
- Enter your Autotask credentials when prompted (Username, Secret, Integration Code)
No terminal, no JSON editing, no Node.js install required.
Claude Code (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:asachs01/autotask-mcp
See Installation for Docker and from-source methods.
Features
- 🔌 MCP Protocol Compliance: Full support for MCP resources and tools
- 🛠️ Comprehensive API Coverage: 35 tools spanning companies, contacts, tickets, projects, 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
- Configuration
- Usage
- API Reference
- ID-to-Name Mapping
- HTTP Transport
- Docker Deployment
- Development
- Testing
- Troubleshooting
- Contributing
- Contributors
- License
Installation
Option 1: MCPB Bundle (Claude Desktop)
The simplest method — no terminal, no JSON editing, no Node.js install required.
- Download
autotask-mcp.mcpbfrom the latest release - Open the file (double-click or drag into Claude Desktop)
- Enter your Autotask credentials when prompted (Username, Secret, Integration Code)
For Claude Code (CLI), one command:
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:asachs01/autotask-mcp
Option 2: Docker
Local (stdio — for Claude Desktop or Claude Code):
{
"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/asachs01/autotask-mcp:latest",
"dist/entry.js"
]
}
}
}
Remote (HTTP Streamable — for server deployments):
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/asachs01/autotask-mcp:latest
# Verify
curl http://localhost:8080/health
Clients connect to http://host:8080/mcp using MCP Streamable HTTP transport.
Option 3: From Source (Development)
git clone https://github.com/asachs01/autotask-mcp.git
cd autotask-mcp
npm ci && npm run build
Then point your MCP client at 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"
}
}
}
}
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:
# Required Autotask API credentials
AUTOTASK_USERNAME=your-api-user@example.com
AUTOTASK_SECRET=your-secret-key
AUTOTASK_INTEGRATION_CODE=your-integration-code
# Optional configuration
AUTOTASK_API_URL=https://webservices.autotask.net/atservices/1.6/atws.asmx
MCP_SERVER_NAME=autotask-mcp
# 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
💡 Pro Tip: Copy the above content to a .env file in your project root.
Autotask API Setup
- Create API User: In Autotask, create a dedicated API user with appropriate permissions
- Generate Secret: Generate an API secret for the user
- Integration Code: Obtain your integration code from Autotask
- Permissions: Ensure the API user has read/write access to required entities
For detailed setup instructions, see the Autotask API documentation.
Usage
Command Line
# 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 Client Configuration
See Installation for all setup methods.
API Reference
Resources
Resources provide read-only access to Autotask data:
autotask://companies- List all companiesautotask://companies/{id}- Get specific companyautotask://contacts- List all contactsautotask://contacts/{id}- Get specific contactautotask://tickets- List all ticketsautotask://tickets/{id}- Get specific ticketautotask://time-entries- List time entries
Tools
The server provides 35 tools for interacting with Autotask:
Company Operations
autotask_search_companies- Search companies with filtersautotask_create_company- Create new companyautotask_update_company- Update existing company
Contact Operations
autotask_search_contacts- Search contacts with filtersautotask_create_contact- Create new contact
Ticket Operations
autotask_search_tickets- Search tickets with filtersautotask_get_ticket_details- Get full ticket details by IDautotask_create_ticket- Create new ticket
Time Entry Operations
autotask_create_time_entry- Log time entry
Project Operations
autotask_search_projects- Search projects with filtersautotask_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_noteautotask_get_project_note/autotask_search_project_notes/autotask_create_project_noteautotask_get_company_note/autotask_search_company_notes/autotask_create_company_note
Attachment Operations
autotask_get_ticket_attachment- Get ticket attachmentautotask_search_ticket_attachments- Search ticket attachments
Financial Operations
autotask_get_expense_report/autotask_search_expense_reports/autotask_create_expense_reportautotask_get_quote/autotask_search_quotes/autotask_create_quoteautotask_search_invoices- Search invoicesautotask_search_contracts- Search contracts
Configuration Items
autotask_search_configuration_items- Search configuration items (assets)
Task Operations
autotask_search_tasks- Search project tasksautotask_create_task- Create project task
Utility Operations
autotask_test_connection- Test API connectivity
Example Tool Usage
// 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:
{
"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:
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.
# Start with HTTP transport
MCP_TRANSPORT=http MCP_HTTP_PORT=8080 node dist/index.js
The HTTP transport exposes:
POST /mcp— MCP Streamable HTTP endpointGET /health— Health check (returns{"status":"ok"})
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.
# Pull the latest image
docker pull ghcr.io/asachs01/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/asachs01/autotask-mcp:latest
# Verify it's running
curl http://localhost:8080/health
For stdio usage with Claude Desktop, see Installation Option 2.
Quick Start (From Source)
# Clone repository
git clone https://github.com/asachs01/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
Production Deployment
# 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
Development Mode
# Start development environment with hot reload
docker compose --profile dev up autotask-mcp-dev
Development
Setup
git clone https://github.com/asachs01/autotask-mcp.git
cd autotask-mcp
npm install
Available Scripts
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
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
# 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
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
| Variable | Required | Default | Description |
|---|---|---|---|
AUTOTASK_USERNAME | ✅ | - | Autotask API username (email) |
AUTOTASK_SECRET | ✅ | - | Autotask API secret key |
AUTOTASK_INTEGRATION_CODE | ✅ | - | Autotask integration code |
AUTOTASK_API_URL | ❌ | Auto-detected | Autotask API endpoint URL |
MCP_SERVER_NAME | ❌ | autotask-mcp | MCP server name |
MCP_TRANSPORT | ❌ | stdio | Transport type (stdio or http) |
MCP_HTTP_PORT | ❌ | 8080 | HTTP transport port |
MCP_HTTP_HOST | ❌ | 0.0.0.0 | HTTP transport bind address |
LOG_LEVEL | ❌ | info | Logging level |
LOG_FORMAT | ❌ | simple | Log output format |
NODE_ENV | ❌ | development | Node.js environment |
Logging Levels
error: Only error messageswarn: Warnings and errorsinfo: General information, warnings, and errorsdebug: Detailed debugging information
Log Formats
simple: Human-readable console outputjson: Structured JSON output (recommended for production)
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:
LOG_LEVEL=debug npm start
Health Checks
Test server connectivity:
# 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
MCP Client Issues
Problem: MCP server not appearing in Claude Desktop Solutions:
- Check configuration file syntax (valid JSON)
- Verify file path in the configuration
- Ensure environment variables are set correctly
- 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:
- Check network connectivity to Autotask API
- Enable debug logging (
LOG_LEVEL=debug) to identify bottlenecks - 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
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - 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
| Avatar | Name | Contributions |
|---|---|---|
 | @asachs01 | Maintainer |
 | @Baphomet480 | CLI bin fix |
Support
Acknowledgments
- Model Context Protocol by Anthropic
- Autotask REST API by Kaseya
- autotask-node library
Built with ❤️ for the Autotask and AI community