swag-mcp

SWAG MCP

MCP server for managing SWAG reverse-proxy configuration files, backups, logs, and health checks. Uses a single swag action router backed by local filesystem or SSH-accessible SWAG config storage.

Overview

SWAG MCP generates and manages nginx subdomain proxy configurations for SWAG (Secure Web Application Gateway). Every generated config includes MCP-compatible security headers unconditionally, making configs suitable for both standard web services and MCP/AI services.

What this repository ships

• swag_mcp/: server, config, middleware, models, services, tools, and templates
• config/: local config and test assets
• docs/: template notes, test commands, and design records
• .claude-plugin/, .codex-plugin/, gemini-extension.json: client manifests
• docker-compose.yaml, Dockerfile, entrypoint.sh: container deployment

MCP surface

Tool

Tool	Purpose
swag	Unified action router for config, logs, backups, and health checks
swag_help	Return help for the SWAG MCP server — lists all available actions and sub-actions

Actions

Action	Purpose	Required params
list	List config files	none
create	Create a new reverse-proxy config	config_name, server_name, upstream_app, upstream_port
view	View config contents	config_name
edit	Replace config contents	config_name, new_content
update	Update a specific field	config_name, update_field, update_value
remove	Remove a config	config_name
logs	Read SWAG logs	none
backups	List or clean up backup files	backup_action
health_check	Probe a service endpoint	domain

Resources

URI	Type	Description
swag://	Directory	All active .conf files (excluding .sample)
swag://configs/live	Stream	Real-time config change events
swag://health/stream	Stream	Real-time health status for monitored services
swag://logs/stream	Stream	Live nginx error log tail

Installation

Plugin (recommended)

Install as a Claude Code plugin. You will be prompted for:

• SWAG Proxy Configs Path -- local path to proxy-confs directory
• SWAG MCP Server URL -- base URL of the running HTTP server
• SWAG MCP API Token -- bearer token for the HTTP server

The plugin connects to the server's native streamable-HTTP endpoint.

/plugin marketplace add jmagar/claude-homelab
/plugin install swag-mcp @jmagar-claude-homelab

The plugin uses native HTTP transport and appends /mcp to the configured server URL.

Docker Compose

cp .env.example .env
chmod 600 .env
# Edit .env with your paths and token
docker compose up -d

The container always runs on internal port 8000. Compose publishes it on 127.0.0.1:49152 by default; set SWAG_MCP_PORT to control the host port and SWAG_MCP_BIND_ADDRESS only when you intentionally expose it beyond loopback.

Local development

just setup       # copies .env.example and runs uv sync
just dev         # starts the server

Configuration

Two deployment paths are supported:

Path	Transport	Credentials	Auth
Plugin (HTTP)	http	userConfig in plugin settings	Bearer token
Docker (HTTP)	http	.env file	Bearer token

See docs/CONFIG.md for full variable reference. All variables use the SWAG_MCP_ prefix.

Core

Variable	Required	Default	Description
SWAG_MCP_PROXY_CONFS_PATH	no	/swag/nginx/proxy-confs	Local path to SWAG proxy confs directory
SWAG_MCP_PROXY_CONFS_URI	no	``	Overrides PROXY_CONFS_PATH when set. Accepts a local path or SSH URI.
SWAG_MCP_SWAG_LOG_BASE_PATH	no	/swag/log	Base path for SWAG log files (local or remote)
SWAG_MCP_TEMPLATE_PATH	no	templates	Path to Jinja2 templates directory

Server

Variable	Required	Default	Description
SWAG_MCP_HOST	no	127.0.0.1	Bind address for the MCP server
SWAG_MCP_BIND_ADDRESS	no	127.0.0.1	Docker host bind address for the published MCP port
SWAG_MCP_PORT	no	49152	Host-side port (Docker only; container always uses 8000)
SWAG_MCP_TOKEN	recommended	``	Bearer token enforced by FastMCP for direct MCP server access
SWAG_MCP_NO_AUTH	no	false	Set true only for loopback/proxy-isolated deployments without server auth

Defaults