Skip to main content
Glama

Autotask MCP Server

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

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

  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

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

  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:

{ "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:

  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_URLAuto-detectedAutotask API endpoint URL
MCP_SERVER_NAMEautotask-mcpMCP server name
MCP_SERVER_VERSION1.0.0MCP server version
LOG_LEVELinfoLogging level
LOG_FORMATsimpleLog output format
NODE_ENVdevelopmentNode.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

Related MCP Servers

  • -
    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
  • -
    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
  • 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
    • Apple
    • Linux
  • -
    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

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