{"id":46533648,"url":"https://github.com/wyre-technology/autotask-mcp","last_synced_at":"2026-04-09T20:17:24.342Z","repository":{"id":317562311,"uuid":"999726754","full_name":"wyre-technology/autotask-mcp","owner":"wyre-technology","description":"MCP server for Kaseya Autotask PSA — 39 tools for companies, tickets, projects, time entries, and more","archived":false,"fork":false,"pushed_at":"2026-03-31T21:17:46.000Z","size":1787,"stargazers_count":28,"open_issues_count":4,"forks_count":24,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-04-03T01:44:08.432Z","etag":null,"topics":["ai-tools","autotask","claude","kaseya","mcp","model-context-protocol","msp","psa","wyre-technology"],"latest_commit_sha":null,"homepage":"https://mcp.wyretechnology.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wyre-technology.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":"CLA.md"}},"created_at":"2025-06-10T17:33:40.000Z","updated_at":"2026-04-02T23:26:52.000Z","dependencies_parsed_at":"2025-10-01T18:24:40.421Z","dependency_job_id":"5f3d6368-afce-46e1-b8cf-f27d79aefa02","html_url":"https://github.com/wyre-technology/autotask-mcp","commit_stats":null,"previous_names":["asachs01/autotask-mcp","wyre-technology/autotask-mcp"],"tags_count":58,"template":false,"template_full_name":null,"purl":"pkg:github/wyre-technology/autotask-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyre-technology%2Fautotask-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyre-technology%2Fautotask-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyre-technology%2Fautotask-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyre-technology%2Fautotask-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wyre-technology","download_url":"https://codeload.github.com/wyre-technology/autotask-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wyre-technology%2Fautotask-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31479006,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-06T14:34:32.243Z","status":"ssl_error","status_checked_at":"2026-04-06T14:34:31.723Z","response_time":112,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","autotask","claude","kaseya","mcp","model-context-protocol","msp","psa","wyre-technology"],"created_at":"2026-03-06T23:00:51.588Z","updated_at":"2026-04-09T20:17:24.333Z","avatar_url":"https://github.com/wyre-technology.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Autotask MCP Server\n\n[![Build Status](https://github.com/wyre-technology/autotask-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/wyre-technology/autotask-mcp/actions/workflows/release.yml)\n[![codecov](https://codecov.io/gh/wyre-technology/autotask-mcp/graph/badge.svg)](https://codecov.io/gh/wyre-technology/autotask-mcp)\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)\n\n**Give your AI assistant direct access to Autotask.** Search tickets, create time entries, look up companies, manage projects — all through natural language. No more copy-pasting between browser tabs and chat windows.\n\nThis is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects Claude (or any MCP-compatible AI) to your Autotask PSA environment. Your AI assistant gets 39 tools covering the operations MSP teams use daily: ticket triage, time logging, company lookups, project management, billing review, and more.\n\nIf you run an MSP on Autotask and you're tired of the context-switching tax, this is for you.\n\n\u003e **Part of the [MSP Claude Plugins](https://github.com/wyre-technology/msp-claude-plugins) ecosystem** — a growing suite of AI integrations for the MSP stack including [Datto RMM](https://github.com/wyre-technology/datto-rmm-mcp), [IT Glue](https://github.com/wyre-technology/itglue-mcp), [HaloPSA](https://github.com/wyre-technology/halopsa-mcp), [ConnectWise Automate](https://github.com/wyre-technology/connectwise-automate-mcp), [NinjaOne](https://github.com/wyre-technology/ninjaone-mcp), [Huntress](https://github.com/wyre-technology/huntress-mcp), and more. Built by MSPs, for MSPs.\n\n\u003ca href=\"https://glama.ai/mcp/servers/@wyre-technology/autotask-mcp\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@wyre-technology/autotask-mcp/badge\" alt=\"Autotask MCP server\" /\u003e\n\u003c/a\u003e\n\n## One-Click Deployment\n\n[![Deploy to DO](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/wyre-technology/autotask-mcp/tree/main)\n\n[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/wyre-technology/autotask-mcp)\n\n## Quick Start\n\n**Claude Desktop** — download, open, done:\n\n1. Download `autotask-mcp.mcpb` from the [latest release](https://github.com/wyre-technology/autotask-mcp/releases/latest)\n2. Open the file (double-click or drag into Claude Desktop)\n3. Enter your Autotask credentials when prompted (Username, Secret, Integration Code)\n\nNo terminal, no JSON editing, no Node.js install required.\n\n**Claude Code (CLI):**\n\n```bash\nclaude mcp add autotask-mcp \\\n  -e AUTOTASK_USERNAME=your-user@company.com \\\n  -e AUTOTASK_SECRET=your-secret \\\n  -e AUTOTASK_INTEGRATION_CODE=your-code \\\n  -- npx -y github:wyre-technology/autotask-mcp\n```\n\nSee [Installation](#installation) for Docker and from-source methods.\n\n## Features\n\n- **🔌 MCP Protocol Compliance**: Full support for MCP resources and tools\n- **🛠️ Comprehensive API Coverage**: 39 tools spanning companies, contacts, tickets, projects, billing items, time entries, notes, attachments, and more\n- **🔍 Advanced Search**: Powerful search capabilities with filters across all entities\n- **📝 CRUD Operations**: Create, read, update operations for core Autotask entities\n- **🔄 ID-to-Name Mapping**: Automatic resolution of company and resource IDs to human-readable names\n- **⚡ Intelligent Caching**: Smart caching system for improved performance and reduced API calls\n- **🔒 Secure Authentication**: Enterprise-grade API security with Autotask credentials\n- **🌐 Dual Transport**: Supports both stdio (local) and HTTP Streamable (remote/Docker) transports\n- **📦 MCPB Packaging**: One-click installation via MCP Bundle for desktop clients\n- **🐳 Docker Ready**: Containerized deployment with HTTP transport and health checks\n- **📊 Structured Logging**: Comprehensive logging with configurable levels and formats\n- **🧪 Test Coverage**: Comprehensive test suite with 80%+ coverage\n\n## Table of Contents\n\n- [Installation](#installation)\n- [Configuration](#configuration)\n  - [Gateway Mode](#gateway-mode)\n- [Usage](#usage)\n- [API Reference](#api-reference)\n- [ID-to-Name Mapping](#id-to-name-mapping)\n- [HTTP Transport](#http-transport)\n- [Docker Deployment](#docker-deployment)\n- [Migration Guide](docs/MIGRATION_GUIDE.md)\n- [Development](#development)\n- [Testing](#testing)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [Contributors](#contributors)\n- [License](#license)\n\n## Installation\n\n### Option 1: MCPB Bundle (Claude Desktop)\n\nThe simplest method — no terminal, no JSON editing, no Node.js install required.\n\n1. Download `autotask-mcp.mcpb` from the [latest release](https://github.com/wyre-technology/autotask-mcp/releases/latest)\n2. Open the file (double-click or drag into Claude Desktop)\n3. Enter your Autotask credentials when prompted (Username, Secret, Integration Code)\n\nFor **Claude Code (CLI)**, one command:\n\n```bash\nclaude mcp add autotask-mcp \\\n  -e AUTOTASK_USERNAME=your-user@company.com \\\n  -e AUTOTASK_SECRET=your-secret \\\n  -e AUTOTASK_INTEGRATION_CODE=your-code \\\n  -- npx -y github:wyre-technology/autotask-mcp\n```\n\n### Option 2: Docker\n\n**Local (stdio — for Claude Desktop or Claude Code):**\n\n```json\n{\n  \"mcpServers\": {\n    \"autotask\": {\n      \"command\": \"docker\",\n      \"args\": [\n        \"run\", \"--rm\", \"-i\",\n        \"-e\", \"MCP_TRANSPORT=stdio\",\n        \"-e\", \"AUTOTASK_USERNAME=your-user@company.com\",\n        \"-e\", \"AUTOTASK_SECRET=your-secret\",\n        \"-e\", \"AUTOTASK_INTEGRATION_CODE=your-code\",\n        \"--entrypoint\", \"node\",\n        \"ghcr.io/wyre-technology/autotask-mcp:latest\",\n        \"dist/entry.js\"\n      ]\n    }\n  }\n}\n```\n\n**Remote (HTTP Streamable — for server deployments):**\n\n```bash\ndocker run -d \\\n  --name autotask-mcp \\\n  -p 8080:8080 \\\n  -e AUTOTASK_USERNAME=\"your-user@company.com\" \\\n  -e AUTOTASK_SECRET=\"your-secret\" \\\n  -e AUTOTASK_INTEGRATION_CODE=\"your-code\" \\\n  --restart unless-stopped \\\n  ghcr.io/wyre-technology/autotask-mcp:latest\n\n# Verify\ncurl http://localhost:8080/health\n```\n\nClients connect to `http://host:8080/mcp` using MCP Streamable HTTP transport.\n\n**Gateway Mode (for MCP Gateway deployments):**\n\nWhen deploying behind an MCP Gateway that injects credentials via HTTP headers:\n\n```bash\ndocker run -d \\\n  --name autotask-mcp \\\n  -p 8080:8080 \\\n  -e AUTH_MODE=gateway \\\n  --restart unless-stopped \\\n  ghcr.io/wyre-technology/autotask-mcp:latest\n```\n\nThe gateway injects credentials via headers:\n- `X-API-Key`: Autotask username\n- `X-API-Secret`: Autotask secret\n- `X-Integration-Code`: Autotask integration code\n\nSee [Gateway Mode](#gateway-mode) for details.\n\n### Option 3: From Source (Development)\n\n```bash\ngit clone https://github.com/wyre-technology/autotask-mcp.git\ncd autotask-mcp\nnpm ci \u0026\u0026 npm run build\n```\n\nThen point your MCP client at `dist/entry.js`:\n\n```json\n{\n  \"mcpServers\": {\n    \"autotask\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/autotask-mcp/dist/entry.js\"],\n      \"env\": {\n        \"AUTOTASK_USERNAME\": \"your-user@company.com\",\n        \"AUTOTASK_SECRET\": \"your-secret\",\n        \"AUTOTASK_INTEGRATION_CODE\": \"your-code\"\n      }\n    }\n  }\n}\n```\n\n### Prerequisites\n\n- Valid Autotask API credentials (API user email, secret, integration code)\n- MCP-compatible client (Claude Desktop, Claude Code, etc.)\n- Docker (for Option 2) or Node.js 18+ (for Option 3)\n\n## Configuration\n\n### Environment Variables\n\nCreate a `.env` file with your configuration:\n\n```bash\n# Required Autotask API credentials (Local Mode)\nAUTOTASK_USERNAME=your-api-user@example.com\nAUTOTASK_SECRET=your-secret-key\nAUTOTASK_INTEGRATION_CODE=your-integration-code\n\n# Optional configuration\n# AUTOTASK_API_URL is auto-detected from AUTOTASK_USERNAME via Autotask's\n# unauthenticated zoneInformation endpoint on first connect. Only set this\n# explicitly to override auto-detection (e.g. for an on-prem proxy).\n# AUTOTASK_API_URL=https://webservices2.autotask.net/atservicesrest/\nMCP_SERVER_NAME=autotask-mcp\n\n# Authentication mode\nAUTH_MODE=env               # env (local), gateway (hosted)\n\n# Transport (stdio for local/desktop, http for remote/Docker)\nMCP_TRANSPORT=stdio          # stdio, http\nMCP_HTTP_PORT=8080           # HTTP transport port (only used when MCP_TRANSPORT=http)\nMCP_HTTP_HOST=0.0.0.0        # HTTP transport bind address\n\n# Logging\nLOG_LEVEL=info          # error, warn, info, debug\nLOG_FORMAT=simple       # simple, json\n\n# Environment\nNODE_ENV=production\n```\n\n### Gateway Mode\n\nWhen deployed behind an MCP Gateway (e.g., `mcp.wyre.ai`), the server operates in gateway mode where credentials are injected via HTTP headers on each request.\n\n**Enable Gateway Mode:**\n\n```bash\nAUTH_MODE=gateway\nMCP_TRANSPORT=http\n```\n\n**Expected Headers:**\n\n| Header | Description |\n|--------|-------------|\n| `X-API-Key` | Autotask API username (email) |\n| `X-API-Secret` | Autotask API secret key |\n| `X-Integration-Code` | Autotask integration code |\n| `X-API-URL` | (Optional) Custom Autotask API URL |\n\n**Health Check Response (Gateway Mode):**\n\n```json\n{\n  \"status\": \"ok\",\n  \"transport\": \"http\",\n  \"authMode\": \"gateway\",\n  \"timestamp\": \"2026-02-05T10:00:00.000Z\"\n}\n```\n\nFor detailed migration instructions, see the [Migration Guide](docs/MIGRATION_GUIDE.md).\n\n💡 **Pro Tip**: Copy the above content to a `.env` file in your project root.\n\n### Autotask API Setup\n\n1. **Create API User**: In Autotask, create a dedicated API user with appropriate permissions\n2. **Generate Secret**: Generate an API secret for the user\n3. **Integration Code**: Obtain your integration code from Autotask\n4. **Permissions**: Ensure the API user has read/write access to required entities\n\nFor detailed setup instructions, see the [Autotask API documentation](https://ww3.autotask.net/help/DeveloperHelp/Content/AdminSetup/2ExtensionsIntegrations/APIs/REST/REST_API_Home.htm).\n\n## Usage\n\n### Command Line\n\n```bash\n# Start the MCP server (stdio transport, for piping to an MCP client)\nnode dist/entry.js\n\n# Start with HTTP transport\nMCP_TRANSPORT=http node dist/index.js\n```\n\n### MCP Client Configuration\n\nSee [Installation](#installation) for all setup methods.\n\n## API Reference\n\n### Resources\n\nResources provide read-only access to Autotask data:\n\n- `autotask://companies` - List all companies\n- `autotask://companies/{id}` - Get specific company\n- `autotask://contacts` - List all contacts  \n- `autotask://contacts/{id}` - Get specific contact\n- `autotask://tickets` - List all tickets\n- `autotask://tickets/{id}` - Get specific ticket\n- `autotask://time-entries` - List time entries\n\n### Tools\n\nThe server provides 39 tools for interacting with Autotask:\n\n#### Company Operations\n- `autotask_search_companies` - Search companies with filters\n- `autotask_create_company` - Create new company\n- `autotask_update_company` - Update existing company\n\n#### Contact Operations\n- `autotask_search_contacts` - Search contacts with filters\n- `autotask_create_contact` - Create new contact\n\n#### Ticket Operations\n- `autotask_search_tickets` - Search tickets with filters\n- `autotask_get_ticket_details` - Get full ticket details by ID\n- `autotask_create_ticket` - Create new ticket\n\n#### Time Entry Operations\n- `autotask_create_time_entry` - Log time entry\n- `autotask_search_time_entries` - Search time entries with filters (resource, ticket, project, date range)\n\n#### Billing Items (Approve and Post Workflow)\n- `autotask_search_billing_items` - Search approved and posted billing items\n- `autotask_get_billing_item` - Get specific billing item by ID\n- `autotask_search_billing_item_approval_levels` - Search multi-level approval records for time entries\n\n#### Project Operations\n- `autotask_search_projects` - Search projects with filters\n- `autotask_create_project` - Create new project\n\n#### Resource Operations\n- `autotask_search_resources` - Search resources (technicians/users)\n\n#### Note Operations\n- `autotask_get_ticket_note` / `autotask_search_ticket_notes` / `autotask_create_ticket_note`\n- `autotask_get_project_note` / `autotask_search_project_notes` / `autotask_create_project_note`\n- `autotask_get_company_note` / `autotask_search_company_notes` / `autotask_create_company_note`\n\n#### Attachment Operations\n- `autotask_get_ticket_attachment` - Get ticket attachment\n- `autotask_search_ticket_attachments` - Search ticket attachments\n\n#### Financial Operations\n- `autotask_get_expense_report` / `autotask_search_expense_reports` / `autotask_create_expense_report`\n- `autotask_get_quote` / `autotask_search_quotes` / `autotask_create_quote`\n- `autotask_search_invoices` - Search invoices\n- `autotask_search_contracts` - Search contracts\n\n#### Configuration Items\n- `autotask_search_configuration_items` - Search configuration items (assets)\n\n#### Task Operations\n- `autotask_search_tasks` - Search project tasks\n- `autotask_create_task` - Create project task\n\n#### Utility Operations\n- `autotask_test_connection` - Test API connectivity\n\n### Example Tool Usage\n\n```javascript\n// Search for companies\n{\n  \"name\": \"autotask_search_companies\",\n  \"arguments\": {\n    \"searchTerm\": \"Acme Corp\",\n    \"isActive\": true,\n    \"pageSize\": 10\n  }\n}\n\n// Create a new ticket\n{\n  \"name\": \"autotask_create_ticket\",\n  \"arguments\": {\n    \"companyID\": 12345,\n    \"title\": \"Server maintenance request\",\n    \"description\": \"Need to perform monthly server maintenance\",\n    \"priority\": 2,\n    \"status\": 1\n  }\n}\n```\n\n## ID-to-Name Mapping\n\nThe 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.\n\n### Automatic Enhancement\n\nAll search and detail tools automatically include an `_enhanced` field with resolved names:\n\n```json\n{\n  \"id\": 12345,\n  \"title\": \"Sample Ticket\",\n  \"companyID\": 678,\n  \"assignedResourceID\": 90,\n  \"_enhanced\": {\n    \"companyName\": \"Acme Corporation\",\n    \"assignedResourceName\": \"John Smith\"\n  }\n}\n```\n\n### How It Works\n\nID-to-name mapping is applied automatically to all search and detail tool results. No additional tools are needed — the `_enhanced` field is added transparently to every response that contains company or resource IDs.\n\n### Performance Features\n\n- **Smart Caching**: Names are cached for 30 minutes to reduce API calls\n- **Bulk Operations**: Efficient batch lookups for multiple IDs\n- **Graceful Fallback**: Returns \"Unknown Company (123)\" if lookup fails\n- **Parallel Processing**: Multiple mappings resolved simultaneously\n\n### Testing Mapping\n\nTest the mapping functionality:\n\n```bash\nnpm run test:mapping\n```\n\nFor detailed mapping documentation, see [docs/mapping.md](docs/mapping.md).\n\n## HTTP Transport\n\nThe server supports the MCP Streamable HTTP transport for remote deployments (e.g., Docker, cloud hosting). Set `MCP_TRANSPORT=http` to enable it.\n\n```bash\n# Start with HTTP transport\nMCP_TRANSPORT=http MCP_HTTP_PORT=8080 node dist/index.js\n```\n\nThe HTTP transport exposes:\n- `POST /mcp` — MCP Streamable HTTP endpoint\n- `GET /health` — Health check (returns `{\"status\":\"ok\"}`)\n\nClients must send requests to `/mcp` with `Accept: application/json, text/event-stream` headers per the MCP Streamable HTTP specification.\n\n## Docker Deployment\n\nThe Docker image uses HTTP transport by default (port 8080) with a built-in health check.\n\n### Using Pre-built Image from GitHub Container Registry\n\nThe Docker image defaults to **HTTP transport** on port 8080 — suitable for remote/server deployments where clients connect over the network.\n\n```bash\n# Pull the latest image\ndocker pull ghcr.io/wyre-technology/autotask-mcp:latest\n\n# Run container with HTTP transport (default)\ndocker run -d \\\n  --name autotask-mcp \\\n  -p 8080:8080 \\\n  -e AUTOTASK_USERNAME=\"your-api-user@example.com\" \\\n  -e AUTOTASK_SECRET=\"your-secret-key\" \\\n  -e AUTOTASK_INTEGRATION_CODE=\"your-integration-code\" \\\n  --restart unless-stopped \\\n  ghcr.io/wyre-technology/autotask-mcp:latest\n\n# Verify it's running\ncurl http://localhost:8080/health\n```\n\nFor **stdio** usage with Claude Desktop, see [Installation Option 2](#option-2-docker).\n\n### Quick Start (From Source)\n\n```bash\n# Clone repository\ngit clone https://github.com/wyre-technology/autotask-mcp.git\ncd autotask-mcp\n\n# Create environment file\ncp .env.example .env\n# Edit .env with your credentials\n\n# Start with docker-compose\ndocker compose up -d\n```\n\n### Production Deployment\n\n```bash\n# Build production image locally\ndocker build -t autotask-mcp:latest .\n\n# Run container\ndocker run -d \\\n  --name autotask-mcp \\\n  --env-file .env \\\n  --restart unless-stopped \\\n  autotask-mcp:latest\n```\n\n### Development Mode\n\n```bash\n# Start development environment with hot reload\ndocker compose --profile dev up autotask-mcp-dev\n```\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/wyre-technology/autotask-mcp.git\ncd autotask-mcp\nnpm install\n```\n\n### Available Scripts\n\n```bash\nnpm run dev          # Start development server with hot reload\nnpm run build        # Build for production\nnpm run test         # Run test suite\nnpm run test:watch   # Run tests in watch mode\nnpm run test:coverage # Run tests with coverage\nnpm run lint         # Run ESLint\nnpm run lint:fix     # Fix ESLint issues\n```\n\n### Project Structure\n\n```\nautotask-mcp/\n├── src/\n│   ├── handlers/           # MCP request handlers\n│   ├── mcp/               # MCP server implementation\n│   ├── services/          # Autotask service layer\n│   ├── types/             # TypeScript type definitions\n│   ├── utils/             # Utility functions (config, logger, cache)\n│   ├── entry.ts           # Entry point (stdout guard + .env loader)\n│   └── index.ts           # Server bootstrap (config, logger, server init)\n├── tests/                 # Test files\n├── scripts/               # Build and packaging scripts\n│   └── pack-mcpb.js       # MCPB bundle creation\n├── manifest.json          # MCPB manifest for desktop distribution\n├── Dockerfile             # Container definition (HTTP transport)\n├── docker-compose.yml     # Multi-service orchestration\n└── package.json          # Project configuration\n```\n\n## Testing\n\n### Running Tests\n\n```bash\n# Run all tests\nnpm test\n\n# Run with coverage\nnpm run test:coverage\n\n# Run in watch mode\nnpm run test:watch\n\n# Run specific test file\nnpm test -- tests/autotask-service.test.ts\n```\n\n### Test Categories\n\n- **Unit Tests**: Service layer and utility functions\n- **Integration Tests**: MCP protocol compliance\n- **API Tests**: Autotask API integration (requires credentials)\n\n### Coverage Requirements\n\n- Minimum 80% coverage for all metrics\n- 100% coverage for critical paths (authentication, data handling)\n\n## Configuration Reference\n\n### Environment Variables\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `AUTOTASK_USERNAME` | ✅ | - | Autotask API username (email) |\n| `AUTOTASK_SECRET` | ✅ | - | Autotask API secret key |\n| `AUTOTASK_INTEGRATION_CODE` | ✅ | - | Autotask integration code |\n| `AUTOTASK_API_URL` | ❌ | Auto-detected | Autotask API endpoint URL |\n| `MCP_SERVER_NAME` | ❌ | `autotask-mcp` | MCP server name |\n| `MCP_TRANSPORT` | ❌ | `stdio` | Transport type (`stdio` or `http`) |\n| `MCP_HTTP_PORT` | ❌ | `8080` | HTTP transport port |\n| `MCP_HTTP_HOST` | ❌ | `0.0.0.0` | HTTP transport bind address |\n| `LOG_LEVEL` | ❌ | `info` | Logging level |\n| `LOG_FORMAT` | ❌ | `simple` | Log output format |\n| `NODE_ENV` | ❌ | `development` | Node.js environment |\n\n### Logging Levels\n\n- `error`: Only error messages\n- `warn`: Warnings and errors\n- `info`: General information, warnings, and errors\n- `debug`: Detailed debugging information\n\n### Log Formats\n\n- `simple`: Human-readable console output\n- `json`: Structured JSON output (recommended for production)\n\n## Troubleshooting\n\n### Common Issues\n\n#### Authentication Errors\n\n```\nError: Missing required Autotask credentials\n```\n**Solution**: Ensure all required environment variables are set correctly.\n\n#### Connection Timeouts\n\n```\nError: Connection to Autotask API failed\n```\n**Solutions**:\n- Check network connectivity\n- Verify API endpoint URL\n- Confirm API user has proper permissions\n\n#### Permission Denied\n\n```\nError: User does not have permission to access this resource\n```\n**Solution**: Review Autotask API user permissions and security level settings.\n\n### Debug Mode\n\nEnable debug logging for detailed troubleshooting:\n\n```bash\nLOG_LEVEL=debug npm start\n```\n\n### Health Checks\n\nTest server connectivity:\n\n```bash\n# Run test suite\nnpm run test\n\n# For HTTP transport, check the health endpoint\ncurl http://localhost:8080/health\n# Returns: {\"status\":\"ok\"}\n\n# Test API connection with debug logging\nLOG_LEVEL=debug npm start\n```\n\n### Autotask API Rate Limits\n\n**Problem**: `429 Too Many Requests` or \"thread limit exceeded\" errors when Claude queries aggressively\n\nAutotask enforces **3 concurrent threads per endpoint per API tracking identifier**. When an LLM issues multiple tool calls simultaneously (e.g., searching tickets, companies, and contacts at once), requests can pile up and hit this limit.\n\n**Built-in mitigation**: The underlying `autotask-node` SDK automatically queues excess requests rather than failing immediately. Requests wait for a slot to free up, so you generally won't see 429 errors — but you may notice slower responses under heavy load.\n\n**Critical for team/multi-user deployments**: If multiple users or the MCP Gateway share the **same API credentials**, they compete for the same 3-thread budget. This can cause noticeable slowdowns and, in severe cases, queued requests that time out.\n\n**Solution — one API key per team**: Create a dedicated Autotask API user per team or integration. Each user has an independent `integrationCode` with its own thread budget:\n\n1. **Admin \u003e Resources (Users) \u003e Resources/Users** → Add Resource\n2. Set Security Level to **API User**\n3. Note the username, secret, and integration code\n4. Set `AUTOTASK_USERNAME`, `AUTOTASK_SECRET`, and `AUTOTASK_INTEGRATION_CODE` per team\n\n```\nSupport Team  → AUTOTASK_INTEGRATION_CODE=SUPPORT_TEAM_CODE  (3 threads)\nProjects Team → AUTOTASK_INTEGRATION_CODE=PROJECTS_TEAM_CODE (3 threads, independent)\n```\n\nAdditionally, Autotask limits **10,000 total requests per hour** across all integrations hitting your tenant. If you hit this limit, all integrations will start receiving 429s — another reason to use targeted queries with appropriate filters.\n\n### MCP Client Issues\n\n**Problem**: MCP server not appearing in Claude Desktop\n**Solutions**:\n1. Check configuration file syntax (valid JSON)\n2. Verify file path in the configuration\n3. Ensure environment variables are set correctly\n4. Restart Claude Desktop completely\n\n**Problem**: \"Invalid JSON-RPC message: [dotenv@...] injecting env\" / Server disconnected\n**Cause**: The `autotask-node` library calls `dotenv.config()` at module load time. dotenv v17+ writes status messages via `console.log` to stdout, which corrupts the MCP stdio JSON-RPC channel.\n**Solution**: Ensure you're using `dist/entry.js` (not `dist/index.js`) as the entry point. The entry wrapper redirects `console.log` to stderr before any libraries load.\n\n**Problem**: Slow responses\n**Solutions**:\n1. Check network connectivity to Autotask API\n2. Enable debug logging (`LOG_LEVEL=debug`) to identify bottlenecks\n3. The server caches company/resource names for 30 minutes automatically\n\n### Security Best Practices\n\n- Store credentials in environment variables, not directly in config files\n- Limit Autotask API user permissions to the minimum required\n- Rotate API credentials regularly\n- For Docker deployments, use secrets management rather than plain environment variables\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Follow TypeScript best practices\n- Maintain test coverage above 80%\n- Use conventional commit messages\n- Update documentation for API changes\n- Add tests for new features\n\n## License\n\nThis project is licensed under the **Apache License 2.0**. See the [LICENSE](LICENSE) file for details.\n\n### Contributor License Agreement\n\nBy submitting a pull request, you agree to the terms of our [Contributor License Agreement](CLA.md). This ensures that contributions can be properly licensed and that you have the right to submit the code.\n\n## Contributors\n\n| Avatar | Name | Contributions |\n| --- | --- | --- |\n| \u003ca href=\"https://github.com/asachs01\"\u003e\u003cimg src=\"https://github.com/asachs01.png\" width=\"60\" /\u003e\u003c/a\u003e | [@asachs01](https://github.com/asachs01) | Maintainer |\n| \u003ca href=\"https://github.com/Baphomet480\"\u003e\u003cimg src=\"https://github.com/Baphomet480.png\" width=\"60\" /\u003e\u003c/a\u003e | [@Baphomet480](https://github.com/Baphomet480) | CLI bin fix |\n\n## Support\n\n- 📚 [Documentation](https://github.com/wyre-technology/autotask-mcp/wiki)\n- 🐛 [Issue Tracker](https://github.com/wyre-technology/autotask-mcp/issues)\n- 💬 [Discussions](https://github.com/wyre-technology/autotask-mcp/discussions)\n\n## Acknowledgments\n\n- [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic\n- [Autotask REST API](https://ww3.autotask.net/help/DeveloperHelp/Content/APIs/REST/REST_API_Home.htm) by Kaseya\n- [autotask-node](https://www.npmjs.com/package/autotask-node) library\n\n---\n\nBuilt by [WYRE Technology](https://github.com/wyre-technology) — part of the [MSP Claude Plugins](https://github.com/wyre-technology/msp-claude-plugins) ecosystem ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwyre-technology%2Fautotask-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwyre-technology%2Fautotask-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwyre-technology%2Fautotask-mcp/lists"}