autotask-mcp

A Model Context Protocol (MCP) server for Kaseya Autotask PSA, written in Go.

Provides AI assistants (Claude, GPT, etc.) with structured access to Autotask data and operations: tickets, companies, contacts, projects, time entries, billing, quotes, and more.

Features

• 59 MCP tools covering all major Autotask entity types
• 4 lazy loading meta-tools for progressive tool discovery
• 7 MCP resource templates for direct data access
• Dual transport: stdio (Claude Desktop/Code) + HTTP (gateway deployments)
• Rate limiting: token bucket (5000 req/hour) + 3-thread concurrency limiter
• Circuit breaker: automatic backoff on API failures
• ID-to-name mapping cache with batch preloading and 30-minute per-entry TTL
• Compact response formatting to minimize LLM context usage

Quick Start

Stdio (Claude Desktop / Claude Code)

Set credentials via environment variables or the configuration CLI:

# Option A: Using the config CLI (stores securely in $XDG_CONFIG_HOME or ~/.config/autotask-mcp/config.json with 0600 permissions)
autotask-mcp config set username api_user@company.com
autotask-mcp config set secret your_secret
autotask-mcp config set integration_code YOUR_CODE

# Option B: Using environment variables
export AUTOTASK_USERNAME=api_user@company.com
export AUTOTASK_SECRET=your_secret
export AUTOTASK_INTEGRATION_CODE=YOUR_CODE

# Run pre-flight diagnostics
autotask-mcp --doctor

# Run server
go run .

Pre-flight Diagnostics (Doctor Mode)

Run autotask-mcp --doctor to verify your configuration, API credentials, zone routing, and core entity permissions before launching the MCP server:

autotask-mcp --doctor

Doctor mode checks:

• Configuration file location and file permissions (0600 check)
• Credential completeness and resolution source (environment vs config file)
• REST API connectivity and round-trip latency
• Core entity permissions (Tickets, Companies, Contacts, TimeEntries, Resources)

Configuration CLI

The autotask-mcp config command manages persistent file-based settings in $XDG_CONFIG_HOME/autotask-mcp/config.json (defaults to ~/.config/autotask-mcp/config.json):

# Display the active config file path
autotask-mcp config path

# View all configured settings (secrets are masked)
autotask-mcp config get

# Get a specific value
autotask-mcp config get username

# Set configuration values (creates file with secure 0600 permissions)
autotask-mcp config set username api_user@company.com
autotask-mcp config set secret your_secret
autotask-mcp config set integration_code YOUR_CODE
autotask-mcp config set lazy_loading true

# Remove a configuration key
autotask-mcp config unset lazy_loading

Claude Desktop Configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "autotask": {
      "command": "/path/to/autotask-mcp",
      "env": {
        "AUTOTASK_USERNAME": "api_user@company.com",
        "AUTOTASK_SECRET": "your_secret",
        "AUTOTASK_INTEGRATION_CODE": "YOUR_CODE"
      }
    }
  }
}

HTTP / Container

cp .env.example .env
# Edit .env with your credentials

# With Podman
podman-compose up -d

# With Docker
docker compose up -d

The server starts on port 8080 with endpoints:

• POST /mcp: MCP Streamable HTTP transport
• GET /health: Health check

Gateway Mode

For multi-tenant deployments, set AUTH_MODE=gateway. Credentials are injected per-request via headers:

X-API-Key: username
X-API-Secret: secret
X-Integration-Code: code

Configuration Options

Configuration can be provided via environment variables or file configuration (~/.config/autotask-mcp/config.json). Environment variables take precedence over file configuration.

Variable / Key	Default	Description
AUTOTASK_USERNAME / username	(required)	Autotask API username
AUTOTASK_SECRET / secret	(required)	Autotask API secret
AUTOTASK_INTEGRATION_CODE / integration_code	(required)	Autotask integration code
AUTOTASK_API_URL / api_url	auto-discovered	Override API base URL
MCP_TRANSPORT / transport	stdio	Transport: stdio or http
MCP_HTTP_PORT / http_port	8080	HTTP server port
MCP_HTTP_HOST / http_host	0.0.0.0	HTTP server bind address
AUTH_MODE / auth_mode	env	Authentication mode: env or gateway
LOG_LEVEL / log_level	info	Log level: debug, info, warn, error
LAZY_LOADING / lazy_loading	false	Enable progressive tool discovery and proxying

Available Tools

Core Entities

Category	Tools
Tickets	search, get details, create, update
Companies	search, create, update
Contacts	search, create
Projects	search, create
Tasks	search, create
Resources	search
Time Entries	create, search
Configuration Items	search
Contracts	search

Notes & Attachments

Category	Tools
Ticket Notes	get, search, create
Project Notes	get, search, create
Company Notes	get, search, create
Ticket Attachments	get, search

Financial

Category	Tools
Quotes	get, search, create
Quote Items	get, search, create, update, delete
Opportunities	get, search, create
Invoices	search
Billing Items	get, search
Billing Approvals	search
Expense Reports	get, search, create
Expense Items	create

Catalog

Category	Tools
Products	get, search
Services	get, search
Service Bundles	get, search

Utility

Category	Tools
Connection	test
Picklists	queues, statuses, priorities, field info
Meta-tools	list categories, list tools, execute, router

Architecture

autotask-mcp
├── main.go / config.go / server.go    # Entry point, config, transport setup
├── services/
│   ├── mapping.go                      # Company/resource name cache (batch preload)
│   ├── picklist.go                     # Lazy-loaded field/picklist cache
│   └── formatter.go                    # Compact response formatting
├── tools/                              # 59 MCP tool handlers
│   ├── tickets.go, companies.go, ...   # Entity CRUD tools
│   ├── register.go                     # Shared helpers
│   └── lazy.go                         # Progressive discovery meta-tools
└── resources/                          # 7 MCP resource templates

Built on:

• go-autotask: Autotask REST API client with typed generics
• Go MCP SDK: Official MCP server framework

Building

go build -o autotask-mcp .

Development

# Run tests
go test ./...

# Run with race detector
go test -race ./...

# Vet
go vet ./...

License

Apache 2.0