synology-apm-mcp

MCP server for Synology ActiveProtect Manager (APM), built on the synology-apm-sdk. Exposes APM backup and restore operations, protection plans, M365 and GWS workloads, infrastructure, activities, and logs as Model Context Protocol tools and resources for LLM agents.

Installation

No separate install step is required — every setup below runs synology-apm-mcp on demand via uv's uvx launcher ("command": "uvx", "args": ["synology-apm-mcp"]), which provisions Python 3.11+ and the package itself automatically. Install uv once for your platform (macOS, Windows, or Linux), then follow one of the client setups below. You'll also need a running APM instance and a valid account.

Configure APM Credentials

The MCP server does not collect or store APM credentials itself — it connects using a synology-apm-cli config profile. Configure the default profile once, before installing the MCP server in any client — the config file it writes persists on disk, so there is no need to install the CLI permanently just for this:

uvx synology-apm-cli config set

This walks through host/username/password and writes them to ~/.config/synology-apm/config.toml, with the password optionally stored in the OS keyring. To use a name other than default, pass --profile <name> and select it with the APM_PROFILE environment variable (see Environment Variables below) or synology-apm-mcp --profile <name>.

If the account has two-factor authentication enabled, config set also prompts once for a verification code and registers this device as trusted for the profile — the MCP server itself never handles a two-factor code; it only ever uses whatever trusted device config set already registered for the profile it's pointed at. See "Troubleshooting" below.

Claude Desktop (Cowork)

Prerequisite: the Claude desktop app (Cowork).

1. Open Customize → Plugins → Add marketplace → Add from a repository, and enter the URL synology-apm/apm-sdk-python.
2. In Plugins → Personal, find Synology APM MCP Server and click + to install — this installs the MCP server and its workflow skills together.

This plugin connects using the default synology-apm-cli profile and operator mode. Claude Desktop currently has no UI to change plugin settings after install — if you need a different profile or mode, install manually instead (see Claude Desktop (manual config) below).

Claude Desktop (manual config)

Open Settings → Developer, click Edit Config, and add the following:

{
  "mcpServers": {
    "synology-apm": {
      "command": "uvx",
      "args": ["synology-apm-mcp"],
      "env": {
        "APM_PROFILE": "default",
        "APM_MCP_MODE": "operator"
      }
    }
  }
}

ChatGPT Desktop (Work)

Prerequisite: the ChatGPT desktop app (Work).

1. Open Plugins → Add marketplace, and enter synology-apm/apm-sdk-python as the source.
2. In Plugins → Personal, find synology-apm-mcp and click Install.

This plugin connects using the default synology-apm-cli profile and operator mode. ChatGPT Desktop currently has no UI to change plugin settings after install — if you need a different profile or mode, install manually instead (see ChatGPT Desktop (manual config) below).

ChatGPT Desktop (manual config)

Open ~/.codex/config.toml (shared with the Codex CLI/IDE extension) and add the following:

[mcp_servers.synology-apm]
command = "uvx"
args = ["synology-apm-mcp"]

[mcp_servers.synology-apm.env]
APM_PROFILE = "default"
APM_MCP_MODE = "operator"

Environment Variables

Reference for every variable the env block (see the manual config examples above) accepts.

APM_PROFILE/APM_HOST/APM_USERNAME/APM_PASSWORD/APM_NO_VERIFY_SSL are the same connection settings synology-apm-cli resolves:

APM_PROFILE=lab              # synology-apm-cli config profile to connect with (default: "default")

# Or set connection details directly instead of using a profile:
APM_HOST=apm.corp.com        # Override the profile's host directly (set together with USERNAME/PASSWORD)
APM_USERNAME=admin           # Override the profile's username directly
APM_PASSWORD=secret          # Override the profile's password directly
APM_NO_VERIFY_SSL=true       # Skip SSL verification, overriding the profile's own setting in
                             # either direction (also accepts "false" to force verification
                             # back on over a profile that has it disabled)

MCP-specific settings, with no synology-apm-cli equivalent:

Operation Modes

Set APM_MCP_MODE (default: operator) to control which tools are available:

Tools not available in the current mode are never registered on the server process: they are hidden from the agent's tools/list response and cannot be invoked via tools/call, regardless of how a client learns their name.

Audit Log

To record a JSON audit trail of all mutating operations, set APM_MCP_AUDIT_LOG to a file path:

"env": {
  "APM_MCP_AUDIT_LOG": "/var/log/apm-mcp-audit.jsonl",
  ...
}

Each line is a JSON object:

{"ts": "2026-07-15T10:30:00Z", "tool": "backup_machine_workload", "params": {"workload_id": "123e4567-e89b-12d3-a456-426614174001"}, "outcome": "ok"}

Troubleshooting

The server always starts, whether or not it can actually reach APM: no connection settings found at all, an invalid or expired password, an unreachable host, a self-signed certificate without APM_NO_VERIFY_SSL set, a target that is not the primary APM management server, or a two-factor-enabled account with no valid trusted device registered for the profile, all print a diagnostic line to stderr (visible when running synology-apm-mcp directly, or in the host application's MCP server logs, e.g. Claude Desktop's Developer settings) but do not stop the process. Every tool call then returns a JSON error describing the failure together with a hint to reconfigure: re-run uvx synology-apm-cli config set, fix the APM_HOST/APM_USERNAME/APM_PASSWORD/ APM_NO_VERIFY_SSL environment variables directly, or select a different configured profile via APM_PROFILE, then restart the MCP server. For the two-factor case specifically, the MCP server never prompts for a code itself — run uvx synology-apm-cli config set (with --profile <name> for a non-default profile) once to complete the two-factor prompt and register a trusted device, then restart the MCP server.

The one case that does exit immediately at startup is an unrecognized APM_MCP_MODE value — that is a deployment misconfiguration, not a credentials problem, and there is no sensible set of tools to register without knowing which mode was intended.

Available Tools

The MCP server exposes tools across seven domains:

• Infrastructure: site info, backup servers, remote storage, hypervisors
• Machine workloads: list, get, backup, cancel, versions, lock/unlock, file servers, change plan, retire, delete
• M365 workloads: list, get, backup, cancel, versions, lock/unlock, exports, auto backup rules, collaboration settings, change plan, retire, delete, tenant lookup
• GWS workloads: list, get, backup, cancel, versions, lock/unlock, auto backup rules, collaboration settings, protected account types, change plan, retire, delete, domain lookup
• Plans: protection, retirement, and tiering plans — list, get, create, update, delete
• Activities: backup and restore activities — list, get, cancel
• Logs: activity, drive, connection, and system logs (DP appliances only)

Plus six MCP resources for stable, small reference data: apm://site (site overview including workload counts by type), apm://servers, apm://plans/protection, apm://plans/retirement, apm://plans/tiering, apm://saas-applications, and the apm://server/{server_id} resource template. For workload queries use the list_machine_workloads, list_m365_workloads, and list_gws_workloads tools, which support filtering (including by backup status, and for Machine workloads also verification status) and pagination. List resources include "truncated": true when the result set exceeds 500 items, indicating that further pages are available via the corresponding list tool. The paginated, filterable list_saas_applications tool (plus get_m365_tenant / get_gws_domain for a single tenant/domain) complements the apm://saas-applications resource for larger tenant/domain lists.

Workflow Skills

When installed via the Claude Desktop (Cowork) or ChatGPT Desktop (Work) plugin, workflow skills are also available (a manually configured server does not get them):

• daily-backup-report — Status report for a time window
• catch-up-overdue-backups — Find and trigger catch-up for overdue/failed workloads
• analyze-storage-capacity — Capacity planning across all servers and remote storage
• generate-billing-report — Compute backup charges per plan, server, workload type, or tenant
• analyze-restore-activities — Summarize and investigate restore activity trends
• workload-inventory — Full inventory of protected workloads by type and status
• export-apm-config — Snapshot of all APM configuration objects
• investigate-backup-failure — Root cause analysis for backup failures
• review-verification-videos — Check backup-verification status and fetch video links for VM/PS workloads
• export-m365-mailboxes — Bulk PST export of Exchange or Group mailboxes
• provision-apm-config — Bulk-create or update APM infrastructure/plans from a config description
• manage-apm-resource — View, update, or remove a single existing resource
• manage-running-jobs-and-version-locks — Cancel a running backup/restore/export job, or lock/unlock a backup version
• reassign-or-retire-workload — Move a workload to a different plan, or retire/delete it
• apm-mcp-conventions — Shared reference (list-vs-get field completeness, pagination, permission modes, update semantics, destructive action preview pattern) the other skills point to; not a task on its own

Local Development

The setups above install and run the published synology-apm-mcp package via uvx. To point a client at your own checkout instead — for testing local changes before they're published — run from the repo root and replace command/args in either manual config above with:

"command": "uv",
"args": ["run", "--directory", "/path/to/apm-sdk-python", "synology-apm-mcp"]

(TOML: command = "uv" / args = ["run", "--directory", "/path/to/apm-sdk-python", "synology-apm-mcp"].) The env block is unchanged either way.