autotask-mcp

asachs01/autotask-mcp

3.4

If you are the rightful owner of autotask-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Autotask MCP Server is a Model Context Protocol server that provides AI assistants with structured access to Kaseya Autotask PSA data and operations.

Tools
9
Resources
0
Prompts
0

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 !

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 .

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

VariableRequiredDefaultDescription
AUTOTASK_USERNAME✅-Autotask API username (email)
AUTOTASK_SECRET✅-Autotask API secret key
AUTOTASK_INTEGRATION_CODE✅-Autotask integration code
AUTOTASK_API_URL❌Auto-detectedAutotask API endpoint URL
MCP_SERVER_NAME❌autotask-mcpMCP server name
MCP_SERVER_VERSION❌1.0.0MCP server version
LOG_LEVEL❌infoLogging level
LOG_FORMAT❌simpleLog output format
NODE_ENV❌developmentNode.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 file for details.

Support

Acknowledgments

Built with ❤️ for the Autotask and AI community