Kopia MCP Server
devpoole2907/kopia-mcp
MCP server para gerenciar backups Kopia via Claude e clientes MCP
Ver no GitHubServidor 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-mcp1 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
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 ... --jsoncommands. - 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— wrapskopia repository status --json.kopia_snapshot_list— wrapskopia snapshot list --json [source_path].kopia_snapshot_stats— summary derived from snapshot list.kopia_policy_show— wrapskopia policy show --json.kopia_maintenance_info— wrapskopia maintenance info --json.
Mutating but non-destructive
kopia_snapshot_create— wrapskopia 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 whenKOPIA_MCP_ALLOW_RESTORE=1.
Restore has multiple gates:
- the tool does not exist unless enabled by env var;
- each call requires
confirm=true; - non-empty targets are refused unless
force=true; - 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
mcpPython package. - A
kopiabinary available to the server. - A Kopia repository that is already connected, or a
KOPIA_CONFIG_PATHpointing 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 to1to registerkopia_restore.KOPIA_MCP_LOG_LEVEL— Python logging level. Default:INFO.MCP_TRANSPORT—stdio,streamable-http, orsse. 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_statusmcp_kopia_kopia_snapshot_listmcp_kopia_kopia_snapshot_statsmcp_kopia_kopia_policy_showmcp_kopia_kopia_maintenance_infomcp_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
--jsonflags snapshot create --descriptionpolicy show --global- restore
--no-overwrite-files,--no-overwrite-directories,--no-overwrite-symlinks
License
MIT