Synapse MCP
MCP server for homelab infrastructure. Provides two tools: flux for Docker/Compose/host management and scout for SSH remote operations.
Version: 2.2.3 | Node.js ≥ 24 | MIT
Overview
Synapse MCP exposes Docker infrastructure and SSH operations as MCP tools. Connect it to any MCP client (Claude Code, Cursor, Gemini) and manage containers, inspect remote files, read logs, and run diagnostics across multiple hosts.
What it includes:
src/ — TypeScript implementation (tools, schemas, services, transport)config/ — Config examples and JSON Schemaskills/synapse/ — Client-facing skill docstests/ — Vitest test suite.claude-plugin/, .codex-plugin/, gemini-extension.json — Client manifests
Tools
flux — Docker infrastructure management
Routes by action, then subaction. Total: 43 subactions.
container (14 subactions)
| Subaction | Description | Destructive |
|---|
list | List containers. Filter by state, name_filter, image_filter, label_filter | — |
inspect | Detailed container info. summary=true for basic info | — |
logs | Container logs. Supports lines, since, until, grep, stream | — |
stats | CPU/memory resource usage. Omit container_id for all containers | — |
top | Running processes inside a container | — |
search | Full-text search across containers | — |
start | Start a stopped container | — |
stop | Stop a running container | Yes |
restart | Stop then start a container | — |
pause | Freeze container processes via cgroups | — |
resume | Unfreeze a paused container | — |
pull | Pull the latest image for a container | — |
recreate | Delete and recreate container. pull=true by default | Yes |
exec | Execute a command inside a running container | Yes |
All subactions accept an optional host field. Destructive subactions require confirmation via MCP elicitation (or SYNAPSE_MCP_ALLOW_DESTRUCTIVE=true).
container:exec parameters: container_id, command, user (optional), workdir (optional), timeout (1000–300000 ms, default 30000).
container:logs parameters: lines (1–500, default 50), since/until (ISO 8601 or relative like "1h"), grep, stream (stdout/stderr/both).
compose (10 subactions)
| Subaction | Description | Destructive |
|---|
list | List all Compose projects. Filter with name_filter | — |
status | Project service status. Filter with service_filter | — |
logs | Project logs. Supports service, lines, since, until, grep | — |
pull | Pull images for a project or specific service | — |
build | Build project images. no_cache=true to force rebuild | — |
up | Start project. detach=true by default | — |
down | Stop and remove containers. remove_volumes=true requires force=true | Yes |
restart | Restart all project services | Yes |
recreate | Recreate all project containers. Requires force=true | Yes |
refresh | Rescan filesystem to refresh Compose project cache | — |
compose:down note: remove_volumes=true AND force=true are both required to delete volumes. This prevents accidental data loss.
compose:logs time filter: Accepts durations (30s, 5m, 1.5h, 100ms), dates (2024-01-01), RFC3339 timestamps, or Unix timestamps.
Default Compose search paths (Unraid-centric defaults, override per host):
/compose/mnt/cache/compose/mnt/cache/code
docker (9 subactions)
| Subaction | Description | Destructive |
|---|
info | Docker daemon information | — |
df | Docker disk usage | — |
images | List images. dangling_only=true for untagged only | — |
networks | List Docker networks | — |
volumes | List Docker volumes | — |
pull | Pull an image by name | — |
build | Build an image. context must be absolute path | — |
rmi | Remove an image. Requires force=true | Yes |
prune | Remove unused resources. prune_target required, force=true required | Yes |
docker:prune targets: containers, images, volumes, networks, buildcache, all.
docker:build parameters: context (absolute path, no ..), tag, dockerfile (relative to context, optional), no_cache.
host (9 subactions)
jmagar