Skip to content
ValentinAUCLERCPublic

About

Clean MCP server for the Atera RMM/PSA API v3 — 47 tools, read-only by default

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

atera-mcp

A clean, read-only-by-default MCP server for the Atera RMM/PSA API v3.

  • Ticket statistics over your whole history (optional): a local SQLite index kept in sync with Atera answers counts, trends, rankings, resolution/first-response times and SLA compliance in milliseconds, over tens of thousands of tickets. See Ticket index and statistics.
  • 50 tools over tickets, customers, contacts, agents (devices), alerts, contracts, knowledge base, billing, custom fields, network devices, departments and rates.
  • Every tool is listed from the first tools/list. No "navigate first" step, no hidden state: works with any MCP host, including gateways and shared/pooled processes.
  • Safe by default: read-only unless you opt in with ATERA_ACCESS=write or full. Tools carry MCP annotations (readOnlyHint, destructiveHint, idempotentHint).
  • Small outputs: list tools return a summary of each item (full=true for every field), null/empty fields are stripped, pages are capped at 50 items.
  • Search helpers for what Atera can't filter server-side: find_customers, find_contacts, find_agents, severity/customer/agent filters on alerts, text search in the knowledge base.
  • Robust client: JWT keys sent as Bearer, legacy keys as X-API-KEY; retries reads on 429/5xx/network errors (honours Retry-After) but never replays a write that may have reached Atera; errors come back as a JSON envelope the model can act on.
  • 2 runtime dependencies: @modelcontextprotocol/sdk and zod.

Quick start

You need Node.js 20+ (22.13+ for the ticket index) and an Atera API key (Atera → Admin → API). Prefer a key with read permissions only, unless you enable write tools.

ATERA_API_KEY=your-key npx -y atera-mcp

npm

Claude Desktop / Claude Code / Cursor

{
  "mcpServers": {
    "atera": {
      "command": "npx",
      "args": ["-y", "atera-mcp"],
      "env": {
        "ATERA_API_KEY": "your-key",
        "ATERA_ACCESS": "read"
      }
    }
  }
}

Pin a version with atera-mcp@0.2.2. Without npm access, the tarball attached to each GitHub release works too, and so does git (slower: it builds on install):

npx -y https://github.com/ValentinAUCLERC/atera-mcp/releases/download/v0.2.2/atera-mcp-0.2.2.tgz
npx -y github:ValentinAUCLERC/atera-mcp#v0.2.2

From source

git clone https://github.com/ValentinAUCLERC/atera-mcp.git
cd atera-mcp
npm ci
npm run build
ATERA_API_KEY=your-key node dist/index.js

Configuration

Variable Default Description
ATERA_API_KEY — (required) Atera API key. JWT tokens are sent as Authorization: Bearer, older keys as X-API-KEY.
ATERA_ACCESS read read = read tools only (32, +3 stats tools with the index), write = + create/update/comment/resolve (+10), full = + delete (+5).
ATERA_TECHNICIAN_EMAIL — Default author of ticket comments (an existing Atera technician). See Comment author.
ATERA_TOOLSETS all Comma-separated subset to expose fewer tools: account, customers, contacts, agents, alerts, tickets, stats, contracts, knowledge, billing, customfields, devices, departments, rates.
ATERA_TIMEOUT_MS 30000 Timeout of one HTTP call to Atera.
ATERA_MAX_RESULT_CHARS 25000 Max size of one tool result. Longer lists are trimmed (whole items, with itemsOmitted) instead of being cut mid-JSON by the client.
ATERA_CACHE_DIR — (disabled) Enables the local ticket index and the stats tools. Directory for the SQLite file (one file per Atera account). Needs Node.js 22.13+.
ATERA_TIMEZONE UTC IANA time zone used for date filters and day/week/month grouping, e.g. Europe/Paris.
ATERA_SYNC_RPM 300 Max Atera requests per minute used by the index sync (capped at 600; Atera allows ~700 for the whole account).
ATERA_SYNC_INTERVAL_MIN 5 Incremental sync period (tickets modified since the last sync).
ATERA_SYNC_FULL_MIN 60 Full reconciliation period (re-reads every ticket, removes deleted ones).
ATERA_SYNC_TIMEOUT_MS 120000 Timeout of one sync request, download included. /tickets pages embed the first comment of each ticket and can be several MB.
ATERA_BASE_URL https://app.atera.com/api/v3 API base URL (tests, proxies).

Example for a helpdesk assistant that only needs tickets and who's who:

ATERA_ACCESS=write ATERA_TOOLSETS=tickets,customers,contacts,agents

Tools

Access: R read, W write (create/update), D delete. W tools need ATERA_ACCESS=write, D tools ATERA_ACCESS=full.

Toolset Tool Access What it does
tickets list_tickets R Tickets by status and/or customer (summary)
tickets list_modified_tickets R Tickets modified since a date, or whose status changed
tickets get_ticket R Full ticket: description, last comments, SLA
tickets list_ticket_comments R Ticket conversation
tickets get_ticket_work_hours R Billable / non-billable time, optionally each entry
tickets list_ticket_attachments R Ticket attachments
tickets create_ticket W Create a ticket for a contact (ID or email)
tickets update_ticket W Status, priority, impact, type, title, technician
tickets add_ticket_comment W Technician comment, internal by default
tickets delete_ticket D Delete a ticket
stats ticket_stats R Counts, open/resolved, resolution & first-response times, SLA %, work hours; grouped by status, priority, type, source, customer, technician, end user or period (needs the index)
stats search_tickets R Tickets filtered by date ranges, technician, end user, title, several statuses (needs the index)
stats ticket_index_status R Index state: tickets indexed, last syncs, progress, last error (needs the index)
customers list_customers R Customers (summary)
customers find_customers R Search by name, domain or business number
customers get_customer R Full customer
customers create_customer / update_customer W Create / update a customer
customers delete_customer D Delete a customer
contacts list_contacts R Contacts, exact email/phone filter
contacts find_contacts R Search by name/email, optionally per customer
contacts get_contact R Full contact
contacts create_contact / update_contact W Create / update (or archive) a contact
contacts delete_contact D Delete a contact
agents list_agents R Monitored machines, optionally per customer
agents find_agents R Search by machine, user, IP, customer; online/offline filter
agents get_agent R Full hardware/OS record
agents get_agent_by_machine R Exact machine name lookup
agents get_agent_patches R Installed or available Windows updates
agents delete_agent D Remove an agent
alerts list_alerts R Alerts by status; severity/customer/agent filters
alerts get_alert R Full alert
alerts create_alert / resolve_alert W Raise / resolve an alert
alerts delete_alert D Delete an alert
account get_account R Account behind the API key
contracts list_contracts / get_contract R Contracts, optionally per customer
knowledge list_kb_articles R Knowledge base, optional text search
billing list_invoices / get_invoice R Invoices
customfields list_custom_field_definitions R Custom field definitions
customfields get_custom_fields R Custom values of a ticket, customer, contact, agent…
customfields set_custom_field W Set a custom value
devices list_devices / get_device R Network devices (generic, TCP, SNMP, HTTP)
departments list_departments / get_department R Departments
rates list_rates R Products or expenses rates

Output shapes

List tools:

{ "items": [ ... ], "page": 1, "totalPages": 4, "totalItems": 73, "hasMore": true }

find_* tools (and filtered list_alerts / list_kb_articles) scan pages of 50 client-side:

{ "items": [ ... ], "scannedPages": 3, "totalPages": 12, "truncated": true }

truncated: true means the scan stopped before the last page (limit reached or maxPages hit): there may be more matches.

Errors (isError: true):

{ "error": { "code": "not_found", "message": "Atera returned HTTP 404 for GET /tickets/99: ...", "status": 404, "retryable": false } }

code is one of invalid_argument, unauthorized, forbidden, not_found, rate_limited, upstream_error, network_error.

Comment author

Atera API keys belong to the account, not to a person, so Atera needs every ticket comment to name an existing technician (otherwise it answers 404 Invalid input). add_ticket_comment picks the author in this order:

  1. The user declared by the MCP client in the tools/call request: _meta.user.email. A chat app that knows who is logged in can sign comments as that person. The model cannot override it, so text inside a ticket can't make the server sign as someone else.
  2. technicianId / technicianEmail passed by the model.
  3. ATERA_TECHNICIAN_EMAIL.

With none of them, the tool returns an error without calling Atera.

{
  "method": "tools/call",
  "params": {
    "name": "add_ticket_comment",
    "arguments": { "ticketId": 123, "comment": "Called the user" },
    "_meta": { "user": { "email": "alice@example.com" } }
  }
}

Ticket index and statistics

Atera's API returns at most 50 tickets per call and can only filter tickets by status and customer. Computing statistics by paging through the API from a chat is slow, expensive in tokens and gives wrong numbers. With ATERA_CACHE_DIR set, the server keeps a local SQLite copy of every ticket's metadata (no comment text) and answers statistics from it.

How it stays up to date:

  1. Initial build, in the background on first start: walks every page of /tickets at ATERA_SYNC_RPM. 40,000 tickets = 800 requests ≈ 3 minutes at the default rate. It is resumable: if the process stops, it continues where it was. When a page is too heavy to download in time (descriptions with inline images…), the page size shrinks (50 → 25 → 10 → 5 → 1) around it, then grows back; a single ticket that still cannot be downloaded is skipped and logged. Until it completes, the stats tools answer "index being built (page x / y)" instead of failing.
  2. Incremental sync every ATERA_SYNC_INTERVAL_MIN: /tickets/lastmodified since the last sync (with a 10-minute overlap). Usually 1 request. A stale index is also refreshed just before answering a question.
  3. Full reconciliation every ATERA_SYNC_FULL_MIN: re-reads everything, which also refreshes fields that do not bump the modification date. A ticket missing from the run is removed only after Atera confirms it is gone (HTTP 404).

After a restart the index is read from disk and caught up incrementally, so keep ATERA_CACHE_DIR on persistent storage (a Docker volume). Every answer includes index.dataAsOf, the time of the last successful sync.

Sizing (measured on 40,000 synthetic tickets): ~10 MB on disk, aggregates over the whole index in under a second, results of a few KB.

Examples of questions it answers: tickets per month over the last two years; average and median resolution time per technician in 2025; open tickets per customer; first-response SLA compliance last quarter; oldest open tickets.

The index lives in the MCP process: the server must stay up for periodic syncs to run. Hosts that stop idle MCP servers simply resume the sync at the next start. If several processes share the same index file (e.g. an old process still running after a configuration change), a lease stored in the database makes sure only one of them syncs; the others just read.

Notes and limits

  • Atera allows about 700 requests per minute per account. find_* tools cost one request per scanned page (10 by default, 40 max). The index sync stays under ATERA_SYNC_RPM.
  • Updates use Atera's partial update endpoints: only the fields you pass are sent.
  • The API key never appears in tool results or logs. Logs go to stderr (stdout is the MCP channel).
  • Endpoints and payloads follow Atera's published Swagger for API v3. The spec is public: the developer portal (https://api.atera.com/devportal) loads it from https://api.atera.com/proxy/publicapi/v3/openapi. If a write misbehaves on your account, please open an issue with the error envelope.

Development

npm ci
npm run typecheck
npm test
npm run build

Tests mock fetch and drive the real MCP server through an in-memory transport, so they need no Atera account.

Releases: push a vX.Y.Z tag; the release workflow builds, tests, publishes to npm (trusted publishing, with provenance) and attaches atera-mcp-X.Y.Z.tgz to the GitHub release.

License

MIT

About

Clean MCP server for the Atera RMM/PSA API v3 — 47 tools, read-only by default

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages