MCP server (AI assistants)

ngbackup-mcp is an NGBackup extension: a Model Context Protocol server that exposes the Web Console’s authenticated REST API as tools an AI assistant can call. Connect it to Claude Code, Claude Desktop or any MCP client and the assistant can list jobs, read a failed job’s log, run or cancel jobs, and inspect clients, volumes, pools and storages — all through the same authenticated, audited channel the Web Console itself uses. Nothing talks to the daemons directly.

Configuration

All configuration lives in the NGBackup conf tree, in /opt/backup/etc/backup-mcp.conf:

Console {
  Name = default
  Address = http://127.0.0.1:9180
  ApiToken = ngbt_xxxxxxxxxxxxxxxx
}

• Address — the Web Console base URL. HTTPS with a self-signed certificate is accepted (the token, not the certificate, is the access gate).
• ApiToken — a personal API token minted in the Web Console (Settings → API tokens). The token carries the minting user’s role, so mint it from an account whose permissions match what you want the assistant to be able to do.

Protect the token file

backup-mcp.conf holds a bearer credential. Keep it root-or-operator readable (chmod 640), like the other files in /opt/backup/etc.

For ad-hoc runs (development, a laptop pointed at a remote console) the environment variables NGBACKUP_MCP_CONF, NGBACKUP_CONSOLE_URL and NGBACKUP_CONSOLE_TOKEN override the conf file.

Connecting a client

Claude Code:

claude mcp add ngbackup -- ngbackup-mcp

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "ngbackup": { "command": "ngbackup-mcp" } } }

The server speaks MCP over stdio; there is no port to open.

Tools

Tool	What it does
list_jobs	Recent jobs with status, level, bytes, errors
job_log	Full Director joblog for one job id
run_job	Run a configured job (optional client/level/pool/storage/when overrides)
cancel_job	Cancel a running job
list_clients	Director clients with version and address
client_status	Live status of one client’s File daemon
director_status	Director overview: running / scheduled / terminated
jobs_health	Per-job success/failure aggregates
list_volumes	Volumes with pool, status, bytes, retention
list_pools	Pools with volume counts and limits
list_storages	Storage daemons/devices known to the Director

Typical prompts once connected: “why did last night’s PG-Cluster backup fail?” (the assistant chains list_jobs → job_log), “run an incremental of srv-files now”, “which volumes are full?”.

Security notes

• Every call is a normal Web Console API request: token-authenticated, role-checked and written to the console audit log like any operator action.
• The server is read-write only to the extent of the tools above — restores, configuration changes and deletions are deliberately not exposed in this version.
• Revoking the token in the Web Console immediately cuts the assistant off.