n8n MCP Backup Server

An MCP (Model Context Protocol) server that lets an AI assistant (Claude Desktop) back up, list, and restore n8n workflows and PostgreSQL databases — all through natural language commands.

"Take a backup of my n8n workflows" → Claude calls the MCP tool → backup uploaded to S3.

---

What it does

Tool	Description
take_backup	Exports all n8n workflows and credentials to a timestamped JSON and uploads to S3
list_backups	Lists available backups in S3, newest first with sizes
restore_backup	Downloads a backup from S3 and imports workflows back into n8n
take_postgres_backup	Streams a pg_dump directly to S3 via multipart upload (no temp file)
list_postgres_backups	Lists available Postgres backups in S3
restore_postgres_backup	Downloads a Postgres backup from S3 and restores via pg_restore

---

Architecture

Claude Desktop
     │
     │  stdio (MCP)
     ▼
mcp-server (FastMCP)
     │
     ├──► n8n API        (export / import workflows)
     ├──► S3 Storage     (store / retrieve backup files)
     └──► PostgreSQL     (pg_dump / pg_restore)

All services run as Docker containers and communicate over an internal Docker network. S3 storage defaults to Garage (self-hosted) but works with any S3-compatible backend (AWS S3, MinIO, etc.).

---

Tech Stack

• Python + FastMCP — MCP server with stdio transport
• boto3 — S3-compatible storage client
• requests — n8n REST API calls
• Docker Compose — orchestrates all services
• Garage v1.3.1 — self-hosted S3-compatible object storage
• PostgreSQL 16 — database with backup/restore support

---

Quick Start

1. Clone the repo

git clone https://github.com/TameemAlkadiki/n8n-mcp-backup.git
cd n8n-mcp-backup

2. Configure environment

cp .env.example .env

Open .env and fill in all required values. See Configuration below.

3. Set up Garage (S3 storage)

Place your garage.toml at ./garage/config/garage.toml.
See the Garage quick-start guide for setup instructions.

4. Start all services

docker compose up -d

5. Initialize Garage buckets

After first boot, create the S3 buckets:

# Apply cluster layout
docker exec garage /garage layout assign -z default -c 1G <NODE_ID>
docker exec garage /garage layout apply --version 1

# Create buckets
docker exec garage /garage bucket create n8n-backup
docker exec garage /garage bucket create postgres-backup

# Create access key and allow bucket access
docker exec garage /garage key create mcp-key
docker exec garage /garage bucket allow n8n-backup --read --write --key mcp-key
docker exec garage /garage bucket allow postgres-backup --read --write --key mcp-key

Copy the generated key ID and secret into your .env as S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY, then restart:

docker compose restart mcp-server

6. Connect Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "n8n-backup": {
      "command": "docker",
      "args": ["exec", "-i", "mcp_backup_server", "python", "server.py"]
    }
  }
}

Restart Claude Desktop. You can now say:

• "Take a backup of my n8n workflows"
• "List available backups"
• "Restore the backup from yesterday"
• "Take a Postgres backup"

---

Configuration

All configuration is via environment variables in .env. Copy .env.example to get started.

Variable	Required	Description
N8N_ENCRYPTION_KEY	✅	32-byte hex key for n8n credential encryption
N8N_API_KEY	✅	n8n API key (Settings → n8n API → Create)
N8N_URL	optional	n8n base URL (default: http://n8n:5678)
GARAGE_RPC_SECRET	✅	Garage cluster RPC secret
GARAGE_ADMIN_TOKEN	✅	Garage admin API token (for web UI)
S3_ACCESS_KEY_ID	✅	S3 access key ID
S3_SECRET_ACCESS_KEY	✅	S3 secret access key
S3_ENDPOINT	optional	S3 endpoint (default: http://garage:3900)
S3_REGION	optional	S3 region (default: us-east-1)
S3_BUCKET	optional	Bucket for n8n backups (default: n8n-backup)
S3_BUCKET_POSTGRES	optional	Bucket for Postgres backups (default: postgres-backup)
POSTGRES_DB	✅	PostgreSQL database name
POSTGRES_USER	✅	PostgreSQL user
POSTGRES_PASSWORD	✅	PostgreSQL password
PG_HOST	optional	Postgres host (default: postgres)
PG_PORT	optional	Postgres port (default: 5432)

---

Project Structure

n8n-mcp-backup/
├── server.py              # FastMCP server — all 6 tools
├── docker-compose.yml     # All services: n8n, mcp-server, garage, postgres
├── Dockerfile             # MCP server container build
├── requirements.txt       # Python dependencies
├── .env.example           # Environment variable template
└── garage/
    └── config/
        └── garage.toml    # Garage storage config (not included — see setup)

---

Notes

• Credentials are not restored by restore_backup — n8n's API does not expose credential secrets on export. After restoring workflows, re-enter credentials manually in n8n Settings → Credentials.
• Multipart upload is used for Postgres backups, meaning no temporary files are written to disk — the dump streams directly from pg_dump to S3.
• The MCP server uses stdio transport — it is spawned per-session by Claude Desktop via docker exec, not run as a persistent HTTP service.

---

License

MIT