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

Want to connect to Claude Desktop in 5 minutes? See our Quick Start Guide for Claude Desktop!

Features

🔌 MCP Protocol Compliance: Full support for MCP resources and tools
🛠️ Comprehensive API Coverage: Access to companies, contacts, tickets, time entries, 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
🐳 Docker Ready: Containerized deployment with Docker and docker-compose
📊 Structured Logging: Comprehensive logging with configurable levels and formats
🧪 Test Coverage: Comprehensive test suite with 80%+ coverage

Installation

Prerequisites

Node.js 18+ (LTS recommended)
Valid Autotask API credentials
MCP-compatible client (Claude Desktop, Continue, etc.)

NPM Installation

npm install -g autotask-mcp

From Source

git clone https://github.com/your-org/autotask-mcp.git
cd autotask-mcp
npm install
npm run build

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
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.

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
autotask-mcp

# Start with custom configuration
AUTOTASK_USERNAME=user@example.com autotask-mcp

MCP Client Configuration

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

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

Tools provide interactive operations:

Company Operations

search_companies - Search companies with filters
create_company - Create new company
update_company - Update existing company

Contact Operations

search_contacts - Search contacts with filters
create_contact - Create new contact

Ticket Operations

search_tickets - Search tickets with filters
create_ticket - Create new ticket

Time Entry Operations

create_time_entry - Log time entry

Utility Operations

test_connection - Test API connectivity

Example Tool Usage

// 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
  }
}

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

Mapping Tools

Additional tools are available for direct ID-to-name resolution:

get_company_name - Get company name by ID
get_resource_name - Get resource (user) name by ID
get_mapping_cache_stats - View cache statistics
clear_mapping_cache - Clear cached mappings
preload_mapping_cache - Preload cache for better performance

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.

Docker Deployment

Quick Start

# Clone repository
git clone https://github.com/your-org/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
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

Claude Desktop Integration

This section explains how to connect the Autotask MCP Server to Claude Desktop for seamless AI-powered Autotask interactions.

Prerequisites

Claude Desktop: Download and install Claude Desktop
MCP Server Running: Have the Autotask MCP server running locally or in Docker
Autotask Credentials: Valid Autotask API credentials configured

Configuration Steps

1. Locate Claude Desktop Configuration

The Claude Desktop configuration file location varies by operating system:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Configure MCP Server Connection

Add 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:

{
  "mcpServers": {
    "autotask": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/path/to/your/.env",
        "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"
      }
    }
  }
}

3. Restart Claude Desktop

After updating the configuration:

Completely quit Claude Desktop
Restart the application
Verify the connection in the Claude interface

Verification

Check MCP Server Status

Look for the MCP server indicator in Claude Desktop:

Connected: Green indicator with "autotask" label
Disconnected: Red indicator or missing server

Test Basic Functionality

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"

Available MCP Resources

Once connected, Claude can access these Autotask resources:

Companies

autotask://companies - List all companies
autotask://companies/{id} - Get specific company details

Contacts

autotask://contacts - List all contacts
autotask://contacts/{id} - Get specific contact details

Tickets

autotask://tickets - List all tickets
autotask://tickets/{id} - Get specific ticket details

Time Entries

autotask://time-entries - List all time entries

Available MCP Tools

Claude can perform these actions via MCP tools:

Company Operations

search_companies: Find companies with filters
create_company: Create new companies
update_company: Modify existing companies

Contact Operations

search_contacts: Find contacts with filters
create_contact: Create new contacts

Ticket Operations

search_tickets: Find tickets with filters
create_ticket: Create new tickets

Time Entry Operations

create_time_entry: Log time entries

Utility Operations

test_connection: Verify Autotask API connectivity

Example Usage Scenarios

1. Ticket Management

Claude, show me all open tickets assigned to John Doe and create a summary report

2. Customer Information

Find the contact information for ACME Corporation and show me their recent tickets

3. Time Tracking

Create a time entry for 2 hours of work on ticket #12345 with description "Database optimization"

4. Company Analysis

Show me all companies created in the last 30 days and their primary contacts

Troubleshooting Claude Integration

Connection Issues

Problem: MCP server not appearing in Claude Solutions:

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

Problem: Authentication errors Solutions:

Verify Autotask credentials are correct
Check API user permissions in Autotask
Ensure integration code is valid

Performance Issues

Problem: Slow responses from Claude Solutions:

Check network connectivity to Autotask API
Monitor server logs for performance bottlenecks
Consider implementing caching for frequently accessed data

Debug Mode

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

Security Considerations

Credential Management

Store credentials in environment variables, not directly in config
Use .env files for local development
Consider using secrets management for production

Network Security

Run MCP server in isolated network environments
Use HTTPS for all API communications
Monitor and log all API access

Access Control

Limit Autotask API user permissions to minimum required
Regular rotation of API credentials
Monitor API usage patterns

Development

Setup

git clone https://github.com/your-org/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
│   └── 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

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_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

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)

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:

# Test basic functionality
npm run test

# Test API connection (requires credentials)
LOG_LEVEL=debug npm start

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 MIT License - see the LICENSE file for details.

Support

Acknowledgments

Built with ❤️ for the Autotask and AI community

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

A Model Context Protocol server that enables natural language querying of Kaseya's Autotask PSA data through AI assistants, supporting contract analysis, ticket tracking, agent activities, and project status monitoring.

Related MCP Servers

Linear MCP Server
emmett-deen
-
security
F
license
-
quality
A Model Context Protocol server implementation that enables AI assistants to interact with Linear project management systems, allowing them to create, retrieve, and modify data related to issues, projects, teams, and users.
Last updated -
15
3
TypeScript
Tiny TODO MCP
tkc
-
security
F
license
-
quality
A Model Context Protocol server that provides persistent task management capabilities for AI assistants, allowing them to create, update, and track tasks beyond their usual context limitations.
Last updated -
3
TypeScript
Agentic Tools MCP Server
Pimzino
A
security
A
license
A
quality
A Model Context Protocol server providing AI assistants with comprehensive project, task, and subtask management capabilities with project-specific storage.
Last updated -
29
25
42
TypeScript
MIT License
kwrds.ai MCP Server
mkotsollaris
-
security
A
license
-
quality
Model Context Protocol server that enables AI assistants to perform keyword research, SEO analysis, and content planning through natural language queries against kwrds.ai's SEO tools.
Last updated -
1
Python
Apache 2.0

View all related MCP servers