Offers containerized deployment options for the Autotask MCP server with production and development configurations
Provides a Node.js implementation for accessing Autotask PSA data, with support for companies, contacts, tickets, and time entries management
Enables structured access to Kaseya Autotask PSA data and operations, including companies, contacts, tickets, time entries with comprehensive CRUD operations and advanced search capabilities
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
- Configuration
- Usage
- API Reference
- ID-to-Name Mapping
- Docker Deployment
- Claude Desktop Integration
- Development
- Testing
- Contributing
- License
Installation
Prerequisites
- Node.js 18+ (LTS recommended)
- Valid Autotask API credentials
- MCP-compatible client (Claude Desktop, Continue, etc.)
NPM Installation
From Source
Configuration
Environment Variables
Create a .env
file with your configuration:
💡 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
MCP Client Configuration
Add to your MCP client configuration (e.g., Claude Desktop):
API Reference
Resources
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 entries
Tools
Tools provide interactive operations:
Company Operations
search_companies
- Search companies with filterscreate_company
- Create new companyupdate_company
- Update existing company
Contact Operations
search_contacts
- Search contacts with filterscreate_contact
- Create new contact
Ticket Operations
search_tickets
- Search tickets with filterscreate_ticket
- Create new ticket
Time Entry Operations
create_time_entry
- Log time entry
Utility Operations
test_connection
- Test API connectivity
Example Tool Usage
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:
Mapping Tools
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 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:
For detailed mapping documentation, see docs/mapping.md.
Docker Deployment
Quick Start
Production Deployment
Development Mode
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:
For Docker Deployment:
For NPM Global Installation:
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:
Available MCP Resources
Once connected, Claude can access these Autotask resources:
Companies
autotask://companies
- List all companiesautotask://companies/{id}
- Get specific company details
Contacts
autotask://contacts
- List all contactsautotask://contacts/{id}
- Get specific contact details
Tickets
autotask://tickets
- List all ticketsautotask://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
2. Customer Information
3. Time Tracking
4. Company Analysis
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:
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
Available Scripts
Project Structure
Testing
Running Tests
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 messageswarn
: Warnings and errorsinfo
: General information, warnings, and errorsdebug
: Detailed debugging information
Log Formats
simple
: Human-readable console outputjson
: Structured JSON output (recommended for production)
Troubleshooting
Common Issues
Authentication Errors
Solution: Ensure all required environment variables are set correctly.
Connection Timeouts
Solutions:
- Check network connectivity
- Verify API endpoint URL
- Confirm API user has proper permissions
Permission Denied
Solution: Review Autotask API user permissions and security level settings.
Debug Mode
Enable debug logging for detailed troubleshooting:
Health Checks
Test server connectivity:
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
- Model Context Protocol by Anthropic
- Autotask REST API by Kaseya
- autotask-node library
Built with ❤️ for the Autotask and AI community
This server cannot be installed
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
- -securityFlicense-qualityA 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 -153TypeScript
- -securityFlicense-qualityA 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 -3TypeScript
- AsecurityAlicenseAqualityA Model Context Protocol server providing AI assistants with comprehensive project, task, and subtask management capabilities with project-specific storage.Last updated -292542TypeScriptMIT License
- -securityAlicense-qualityModel 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 -1PythonApache 2.0