Skip to main content
Glama

Autotask MCP Server

by asachs01
OverviewInspectSchemaRelated ServersScoreDiscussions
TypeScript
Remote
16
13

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!

Related MCP server: Tiny TODO MCP

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

Table of Contents

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

  1. Create API User: In Autotask, create a dedicated API user with appropriate permissions

  2. Generate Secret: Generate an API secret for the user

  3. Integration Code: Obtain your integration code from Autotask

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

Using Pre-built Image from GitHub Container Registry

# 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

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

Claude Desktop Integration

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

Prerequisites

  1. Claude Desktop: Download and install Claude Desktop

  2. MCP Server Running: Have the Autotask MCP server running locally or in Docker

  3. 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 (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" } } } }

3. Restart Claude Desktop

After updating the configuration:

  1. Completely quit Claude Desktop

  2. Restart the application

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

  1. Check configuration file syntax (valid JSON)

  2. Verify file path in the configuration

  3. Ensure environment variables are set correctly

  4. Restart Claude Desktop completely

Problem: Authentication errors Solutions:

  1. Verify Autotask credentials are correct

  2. Check API user permissions in Autotask

  3. Ensure integration code is valid

Performance Issues

Problem: Slow responses from Claude Solutions:

  1. Check network connectivity to Autotask API

  2. Monitor server logs for performance bottlenecks

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

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

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

One-click Deploy
A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

View all tools

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/asachs01/autotask-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server