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

$3

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

$3

``bash
npm install -g autotask-mcp
`

$3

`bash
git clone https://github.com/asachs01/autotask-mcp.git
cd autotask-mcp
npm install
npm run build
`

Configuration

$3

Create a .env file with your configuration:

`bash


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.

$3

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

$3

`bash


Start the MCP server

autotask-mcp

Start with custom configuration

AUTOTASK_USERNAME=user@example.com autotask-mcp
`

$3

Add to your MCP client configuration (e.g., Claude Desktop):

`json
{
"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

$3

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

$3

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

$3

`javascript
// 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.

$3

All search and detail tools automatically include an _enhanced field with resolved names:

`json
{
"id": 12345,
"title": "Sample Ticket",
"companyID": 678,
"assignedResourceID": 90,
"_enhanced": {
"companyName": "Acme Corporation",
"assignedResourceName": "John Smith"
}
}
`

$3

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

$3

- 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

$3

Test the mapping functionality:

`bash
npm run test:mapping
`

For detailed mapping documentation, see docs/mapping.md.

Docker Deployment

$3

`bash


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
`

$3

`bash


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
`

$3

`bash


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
`

$3

`bash


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.

$3

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

$3

#### 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:
`json
{
"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):
`json
{
"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:
`json
{
"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

$3

#### 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"
`

$3

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

$3

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

$3

#### 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
`

$3

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

`json
{
"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"
}
}
}
}
`

$3

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

$3

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

$3

`bash
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
`

$3

`
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

$3

`bash


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
`

$3

- Unit Tests: Service layer and utility functions
- Integration Tests: MCP protocol compliance
- API Tests: Autotask API integration (requires credentials)

$3

- Minimum 80% coverage for all metrics
- 100% coverage for critical paths (authentication, data handling)

Configuration Reference

$3

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

$3

- error: Only error messages
- warn: Warnings and errors
- info: General information, warnings, and errors
- debug: Detailed debugging information

$3

- simple: Human-readable console output
- json: Structured JSON output (recommended for production)

Troubleshooting

$3

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

$3

Enable debug logging for detailed troubleshooting:

`bash
LOG_LEVEL=debug npm start
`

$3

Test server connectivity:

`bash


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

$3

- Follow TypeScript best practices
- Maintain test coverage above 80%
- Use conventional commit messages
- Update documentation for API changes
- Add tests for new features

Publishing

For maintainers: See PUBLISHING.md for detailed instructions on publishing new versions to npm.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

- 📚 Documentation
- 🐛 Issue Tracker
- 💬 Discussions

Acknowledgments

- Model Context Protocol by Anthropic
- Autotask REST API by Kaseya
- autotask-node library

---

Built with ❤️ for the Autotask and AI community