autotask-mcp
Advanced tools
A Model Context Protocol (MCP) server that provides AI assistants with structured access to Kaseya Autotask PSA data and operations.
Want to connect to Claude Desktop in 5 minutes? See our Quick Start Guide for Claude Desktop!
npm install -g autotask-mcp
git clone https://github.com/asachs01/autotask-mcp.git
cd autotask-mcp
npm install
npm run build
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
MCP_SERVER_VERSION=1.0.0
# 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.
For detailed setup instructions, see the Autotask API documentation.
# Start the MCP server
autotask-mcp
# Start with custom configuration
AUTOTASK_USERNAME=user@example.com autotask-mcp
Add to your MCP client configuration (e.g., Claude Desktop):
{
"mcpServers": {
"autotask": {
"command": "autotask-mcp",
"env": {
"AUTOTASK_USERNAME": "your-api-user@example.com",
"AUTOTASK_SECRET": "your-secret-key",
"AUTOTASK_INTEGRATION_CODE": "your-integration-code"
}
}
}
}
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 entriesTools provide interactive operations:
search_companies - Search companies with filterscreate_company - Create new companyupdate_company - Update existing companysearch_contacts - Search contacts with filterscreate_contact - Create new contactsearch_tickets - Search tickets with filterscreate_ticket - Create new ticketcreate_time_entry - Log time entrytest_connection - Test API connectivity// Search for companies
{
"name": "search_companies",
"arguments": {
"searchTerm": "Acme Corp",
"isActive": true,
"pageSize": 10
}
}
// Create a new ticket
{
"name": "create_ticket",
"arguments": {
"companyID": 12345,
"title": "Server maintenance request",
"description": "Need to perform monthly server maintenance",
"priority": 2,
"status": 1
}
}
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.
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"
}
}
Additional tools are available for direct ID-to-name resolution:
get_company_name - Get company name by IDget_resource_name - Get resource (user) name by IDget_mapping_cache_stats - View cache statisticsclear_mapping_cache - Clear cached mappingspreload_mapping_cache - Preload cache for better performanceTest the mapping functionality:
npm run test:mapping
For detailed mapping documentation, see docs/mapping.md.
# Pull the latest image
docker pull ghcr.io/asachs01/autotask-mcp:latest
# Run container with your credentials
docker run -d \
--name autotask-mcp \
-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
# 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
# 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
This section explains how to connect the Autotask MCP Server to Claude Desktop for seamless AI-powered Autotask interactions.
The Claude Desktop configuration file location varies by operating system:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json~/.config/Claude/claude_desktop_config.jsonAdd the Autotask MCP server to your Claude Desktop configuration:
For Local Development:
{
"mcpServers": {
"autotask": {
"command": "node",
"args": ["/path/to/autotask-mcp/dist/index.js"],
"env": {
"AUTOTASK_USERNAME": "your-api-username@company.com",
"AUTOTASK_SECRET": "your-api-secret",
"AUTOTASK_INTEGRATION_CODE": "your-integration-code"
}
}
}
}
For Docker Deployment (GitHub Container Registry):
{
"mcpServers": {
"autotask": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"-e", "AUTOTASK_USERNAME=your-api-username@company.com",
"-e", "AUTOTASK_SECRET=your-api-secret",
"-e", "AUTOTASK_INTEGRATION_CODE=your-integration-code",
"ghcr.io/asachs01/autotask-mcp:latest"
]
}
}
}
For NPM Global Installation:
{
"mcpServers": {
"autotask": {
"command": "npx",
"args": ["autotask-mcp"],
"env": {
"AUTOTASK_USERNAME": "your-api-username@company.com",
"AUTOTASK_SECRET": "your-api-secret",
"AUTOTASK_INTEGRATION_CODE": "your-integration-code"
}
}
}
}
After updating the configuration:
Look for the MCP server indicator in Claude Desktop:
Try these example prompts in Claude:
Show me all companies in Autotask
Create a new ticket for Company ID 123 with title "Server maintenance"
Search for contacts with email containing "@example.com"
Once connected, Claude can access these Autotask resources:
autotask://companies - List all companiesautotask://companies/{id} - Get specific company detailsautotask://contacts - List all contactsautotask://contacts/{id} - Get specific contact detailsautotask://tickets - List all ticketsautotask://tickets/{id} - Get specific ticket detailsautotask://time-entries - List all time entriesClaude can perform these actions via MCP tools:
Claude, show me all open tickets assigned to John Doe and create a summary report
Find the contact information for ACME Corporation and show me their recent tickets
Create a time entry for 2 hours of work on ticket #12345 with description "Database optimization"
Show me all companies created in the last 30 days and their primary contacts
Problem: MCP server not appearing in Claude Solutions:
Problem: Authentication errors Solutions:
Problem: Slow responses from Claude Solutions:
Enable debug logging for troubleshooting:
{
"mcpServers": {
"autotask": {
"command": "node",
"args": ["/path/to/autotask-mcp/dist/index.js"],
"env": {
"AUTOTASK_USERNAME": "your-username",
"AUTOTASK_SECRET": "your-secret",
"AUTOTASK_INTEGRATION_CODE": "your-code",
"LOG_LEVEL": "debug"
}
}
}
}
.env files for local developmentgit clone https://github.com/your-org/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
│ └── index.ts # Main entry point
├── tests/ # Test files
├── plans/ # Project documentation (gitignored)
├── prompt_logs/ # Development logs (gitignored)
├── Dockerfile # Container definition
├── 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
| 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_SERVER_VERSION | ❌ | 1.0.0 | MCP server version |
LOG_LEVEL | ❌ | info | Logging level |
LOG_FORMAT | ❌ | simple | Log output format |
NODE_ENV | ❌ | development | Node.js environment |
error: Only error messageswarn: Warnings and errorsinfo: General information, warnings, and errorsdebug: Detailed debugging informationsimple: Human-readable console outputjson: Structured JSON output (recommended for production)Error: Missing required Autotask credentials
Solution: Ensure all required environment variables are set correctly.
Error: Connection to Autotask API failed
Solutions:
Error: User does not have permission to access this resource
Solution: Review Autotask API user permissions and security level settings.
Enable debug logging for detailed troubleshooting:
LOG_LEVEL=debug npm start
Test server connectivity:
# Test basic functionality
npm run test
# Test API connection (requires credentials)
LOG_LEVEL=debug npm start
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)For maintainers: See PUBLISHING.md for detailed instructions on publishing new versions to npm.
This project is licensed under the MIT License - see the LICENSE file for details.
Built with ❤️ for the Autotask and AI community
FAQs
MCP (Model Context Protocol) server for Kaseya Autotask PSA integration
We found that autotask-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.