convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
devpoole2907

Kopia MCP Server

devpoole2907/kopia-mcp

MCP server para gerenciar backups Kopia via Claude e clientes MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor Model Context Protocol para o Kopia, ferramenta de backup criptografado com deduplicação. Permite que clientes MCP consultem repositórios, inspecionem snapshots, políticas e estado de manutenção, além de disparar backups através da CLI do Kopia.

Instalação

$npx convez-ai devpoole2907/kopia-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Consultar status e histórico de backups de forma conversacional
  • Criar snapshots sob demanda integrado em workflows de IA
  • Inspecionar políticas de backup e estado de manutenção
  • Restaurar arquivos com confirmação e proteção contra sobrescrita
  • Monitorar repositórios Kopia em ambientes containerizados

Veredito

Implementação bem arquitetada e segura de um MCP server para Kopia. O design defensivo (CLI em vez de HTTP, subprocessos sem shell, gates de confirmação para operações destrutivas) e suporte a múltiplos transportes (stdio, HTTP streamable) o tornam adequado para integração em sistemas de backup críticos.

README

A tradução para o português deste README ainda está na fila.

kopia-mcp

A Model Context Protocol (MCP) server for Kopia, the encrypted deduplicating backup tool.

kopia-mcp lets an MCP client query Kopia repositories, inspect snapshots and policies, check maintenance state, and optionally trigger snapshots through Kopia's CLI.

Design

This server intentionally wraps the Kopia CLI instead of Kopia's HTTP API.

  • Uses documented kopia ... --json commands.
  • Runs subprocesses with argument lists, never shell strings.
  • Logs only to stderr so stdio MCP transport stays clean.
  • Can run either as stdio or Streamable HTTP.
  • Restore is disabled by default and must be explicitly enabled.

Verified against Kopia 0.23.0.

Tools

Always exposed

  • kopia_repository_status — wraps kopia repository status --json.
  • kopia_snapshot_list — wraps kopia snapshot list --json [source_path].
  • kopia_snapshot_stats — summary derived from snapshot list.
  • kopia_policy_show — wraps kopia policy show --json.
  • kopia_maintenance_info — wraps kopia maintenance info --json.

Mutating but non-destructive

  • kopia_snapshot_create — wraps kopia snapshot create <source_path> --json.

This creates a new backup snapshot. It does not overwrite local files. Long-running snapshots use KOPIA_MCP_SNAPSHOT_TIMEOUT; if the timeout is exceeded the tool returns status: "started" rather than hanging.

Destructive and disabled by default

  • kopia_restore — only registered when KOPIA_MCP_ALLOW_RESTORE=1.

Restore has multiple gates:

  1. the tool does not exist unless enabled by env var;
  2. each call requires confirm=true;
  3. non-empty targets are refused unless force=true;
  4. when not forced, Kopia is invoked with --no-overwrite-files, --no-overwrite-directories, and --no-overwrite-symlinks.

Snapshot deletion, policy editing, and repository disconnect are not implemented.

Requirements

  • Python 3.10+.
  • The mcp Python package.
  • A kopia binary available to the server.
  • A Kopia repository that is already connected, or a KOPIA_CONFIG_PATH pointing at an existing repository config.

Install locally

python3 -m venv .venv
. .venv/bin/activate
pip install -e .

Run over stdio:

kopia-mcp

Or:

python -m kopia_mcp.server

Streamable HTTP mode

For containerized MCP clients, run it over Streamable HTTP:

MCP_TRANSPORT=streamable-http \
HOST=0.0.0.0 \
PORT=3000 \
MCP_PATH=/mcp \
kopia-mcp

Endpoint:

http://<host>:3000/mcp

Environment variables

  • KOPIA_BINARY — Kopia executable path. Default: kopia.
  • KOPIA_CONFIG_PATH — optional config passed as Kopia global --config-file.
  • KOPIA_MCP_TIMEOUT — timeout seconds for ordinary commands. Default: 60.
  • KOPIA_MCP_SNAPSHOT_TIMEOUT — timeout seconds for snapshot/restore operations. Default: 3600.
  • KOPIA_MCP_ALLOW_RESTORE — set to 1 to register kopia_restore.
  • KOPIA_MCP_LOG_LEVEL — Python logging level. Default: INFO.
  • MCP_TRANSPORT — stdio, streamable-http, or sse. Default: stdio.
  • HOST — HTTP bind host. Default: 127.0.0.1.
  • PORT — HTTP bind port. Default: 8000.
  • MCP_PATH — Streamable HTTP path. Default: /mcp.

Kopia's own environment variables, such as KOPIA_PASSWORD, are inherited by subprocesses.

Docker / Compose

This repo includes a Dockerfile that bundles:

  • Python 3.12
  • Kopia CLI 0.23.0
  • this MCP server

Build:

docker build -t kopia-mcp .

The included compose.yaml is an example for a Forge-style Docker deployment where the existing Kopia stack keeps its config in ../kopia/config and secrets in ../kopia/.env.

It intentionally publishes no host port; clients reach it on a shared Docker network.

Hermes Agent wiring

Example Hermes config:

mcp_servers:
  kopia:
    url: http://mcp-kopia:3000/mcp
    timeout: 120
    connect_timeout: 60

Restart Hermes after adding the MCP server so tools are discovered.

Expected Hermes tool names are prefixed with the server name, for example:

  • mcp_kopia_kopia_repository_status
  • mcp_kopia_kopia_snapshot_list
  • mcp_kopia_kopia_snapshot_stats
  • mcp_kopia_kopia_policy_show
  • mcp_kopia_kopia_maintenance_info
  • mcp_kopia_kopia_snapshot_create

Safety notes

  • Do not mount backup sources read-write unless you need to create snapshots from inside the MCP container.
  • Do not expose the HTTP endpoint publicly. Put it on a private Docker network.
  • Keep .env, Kopia config, cache, and logs out of Git.
  • Keep restore disabled unless you explicitly need it.

Verifying against your Kopia version

If a tool errors because Kopia flags changed, check:

kopia repository status --help
kopia snapshot list --help
kopia snapshot create --help
kopia policy show --help
kopia maintenance info --help
kopia restore --help

The server depends on:

  • global --config-file
  • read-command --json flags
  • snapshot create --description
  • policy show --global
  • restore --no-overwrite-files, --no-overwrite-directories, --no-overwrite-symlinks

License

MIT

Ver o original no GitHub

Bom para

Relacionados