swag-mcp
starsforks
How to install swag-mcp?
jmagar/swag-mcp
$git clone https://github.com/jmagar/swag-mcpSWAG reverse proxy configuration management via MCP. Create, edit, view, and manage nginx proxy configurations with auth integration.
README.md
| 1 | # SWAG MCP |
| 2 | |
| 3 | <!-- mcp-name: tv.tootie/swag-mcp --> |
| 4 | |
| 5 | [](https://pypi.org/project/swag-mcp/) [](https://github.com/jmagar/swag-mcp/pkgs/container/swag-mcp) |
| 6 | |
| 7 | 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. |
| 8 | |
| 9 | ## Overview |
| 10 | |
| 11 | SWAG MCP generates and manages nginx subdomain proxy configurations for [SWAG (Secure Web Application Gateway)](https://github.com/linuxserver/docker-swag). Every generated config includes MCP-compatible security headers unconditionally, making configs suitable for both standard web services and MCP/AI services. |
| 12 | |
| 13 | ## What this repository ships |
| 14 | |
| 15 | - `swag_mcp/`: server, config, middleware, models, services, tools, and templates |
| 16 | - `config/`: local config and test assets |
| 17 | - `docs/`: template notes, test commands, and design records |
| 18 | - `.claude-plugin/`, `.codex-plugin/`, `gemini-extension.json`: client manifests |
| 19 | - `docker-compose.yaml`, `Dockerfile`, `entrypoint.sh`: container deployment |
| 20 | |
| 21 | ## MCP surface |
| 22 | |
| 23 | ### Tool |
| 24 | |
| 25 | | Tool | Purpose | |
| 26 | | --- | --- | |
| 27 | | `swag` | Unified action router for config, logs, backups, and health checks | |
| 28 | | `swag_help` | Return help for the SWAG MCP server — lists all available actions and sub-actions | |
| 29 | |
| 30 | ### Actions |
| 31 | |
| 32 | | Action | Purpose | Required params | |
| 33 | | --- | --- | --- | |
| 34 | | `list` | List config files | none | |
| 35 | | `create` | Create a new reverse-proxy config | `config_name`, `server_name`, `upstream_app`, `upstream_port` | |
| 36 | | `view` | View config contents | `config_name` | |
| 37 | | `edit` | Replace config contents | `config_name`, `new_content` | |
| 38 | | `update` | Update a specific field | `config_name`, `update_field`, `update_value` | |
| 39 | | `remove` | Remove a config | `config_name` | |
| 40 | | `logs` | Read SWAG logs | none | |
| 41 | | `backups` | List or clean up backup files | `backup_action` | |
| 42 | | `health_check` | Probe a service endpoint | `domain` | |
| 43 | |
| 44 | ### Resources |
| 45 | |
| 46 | | URI | Type | Description | |
| 47 | | --- | --- | --- | |
| 48 | | `swag://` | Directory | All active `.conf` files (excluding `.sample`) | |
| 49 | | `swag://configs/live` | Stream | Real-time config change events | |
| 50 | | `swag://health/stream` | Stream | Real-time health status for monitored services | |
| 51 | | `swag://logs/stream` | Stream | Live nginx error log tail | |
| 52 | |
| 53 | ## Installation |
| 54 | |
| 55 | ### Plugin (recommended) |
| 56 | |
| 57 | Install as a Claude Code plugin. You will be prompted for: |
| 58 | |
| 59 | - **SWAG Proxy Configs Path** -- local path to proxy-confs directory |
| 60 | - **SWAG MCP Server URL** -- base URL of the running HTTP server |
| 61 | - **SWAG MCP API Token** -- bearer token for the HTTP server |
| 62 | |
| 63 | The plugin connects to the server's native streamable-HTTP endpoint. |
| 64 | |
| 65 | ```bash |
| 66 | /plugin marketplace add jmagar/claude-homelab |
| 67 | /plugin install swag-mcp @jmagar-claude-homelab |
| 68 | ``` |
| 69 | |
| 70 | The plugin uses native HTTP transport and appends `/mcp` to the configured server URL. |
| 71 | |
| 72 | ### Docker Compose |
| 73 | |
| 74 | ```bash |
| 75 | cp .env.example .env |
| 76 | chmod 600 .env |
| 77 | # Edit .env with your paths and token |
| 78 | docker compose up -d |
| 79 | ``` |
| 80 | |
| 81 | The container always runs on internal port 8000. Compose publishes it on |
| 82 | `127.0.0.1:49152` by default; set `SWAG_MCP_PORT` to control the host port and |
| 83 | `SWAG_MCP_BIND_ADDRESS` only when you intentionally expose it beyond loopback. |
| 84 | |
| 85 | ### Local development |
| 86 | |
| 87 | ```bash |
| 88 | just setup # copies .env.example and runs uv sync |
| 89 | just dev # starts the server |
| 90 | ``` |
| 91 | |
| 92 | ## Configuration |
| 93 | |
| 94 | Two deployment paths are supported: |
| 95 | |
| 96 | | Path | Transport | Credentials | Auth | |
| 97 | |------|-----------|-------------|------| |
| 98 | | **Plugin (HTTP)** | http | `userConfig` in plugin settings | Bearer token | |
| 99 | | **Docker (HTTP)** | http | `.env` file | Bearer token | |
| 100 | |
| 101 | See [docs/CONFIG.md](docs/CONFIG.md) for full variable reference. All variables use the `SWAG_MCP_` prefix. |
| 102 | |
| 103 | ### Core |
| 104 | |
| 105 | | Variable | Required | Default | Description | |
| 106 | | --- | --- | --- | --- | |
| 107 | | `SWAG_MCP_PROXY_CONFS_PATH` | no | `/swag/nginx/proxy-confs` | Local path to SWAG proxy confs directory | |
| 108 | | `SWAG_MCP_PROXY_CONFS_URI` | no | `` | Overrides `PROXY_CONFS_PATH` when set. Accepts a local path or SSH URI. | |
| 109 | | `SWAG_MCP_SWAG_LOG_BASE_PATH` | no | `/swag/log` | Base path for SWAG log files (local or remote) | |
| 110 | | `SWAG_MCP_TEMPLATE_PATH` | no | `templates` | Path to Jinja2 templates directory | |
| 111 | |
| 112 | ### Server |
| 113 | |
| 114 | | Variable | Required | Default | Description | |
| 115 | | --- | --- | --- | --- | |
| 116 | | `SWAG_MCP_HOST` | no | `127.0.0.1` | Bind address for the MCP server | |
| 117 | | `SWAG_MCP_BIND_ADDRESS` | no | `127.0.0.1` | Docker host bind address for the published MCP port | |
| 118 | | `SWAG_MCP_PORT` | no | `49152` | Host-side port (Docker only; container always uses 8000) | |
| 119 | | `SWAG_MCP_TOKEN` | recommended | `` | Bearer token enforced by FastMCP for direct MCP server access | |
| 120 | | `SWAG_MCP_NO_AUTH` | no | `false` | Set `true` only for loopback/proxy-isolated deployments without server auth | |
| 121 | |
| 122 | ### Defaults |
| 123 | |
| 124 | | Variable | Required | Default | Description | |
| 125 | | --- | --- | - |
People who liked this also viewed
6 picksType
- mcp-proxy-for-awsAWS MCP Proxy ServerMCP ServersJul 2026
- pydantic-ai-backendFile Storage & Sandbox Backends for Pydantic AI: console tools for file operations, Docker-isolated sandboxes for safe execution, and permission system with presets for access control. Enables secure multi-user handling and testing in agents via in-memory, local, or containerized storage.MCP ServersJul 2026
- mcp-for-argocdAn implementation of Model Context Protocol (MCP) server for Argo CD.MCP ServersJul 2026
- heroku-mcp-serverHeroku Platform MCP Server using the Heroku CLIMCP ServersJul 2026
- ghost-mcpA Model Context Protocol (MCP) server for interacting with Ghost CMS through LLM interfaces like Claude. Allow you to control your Ghost blog by simply asking Claude etc.MCP ServersApr 2026
- Google DriveUpload, organize, and share files in the cloud. Manage folders, set permissions, and search across stored documents.MCP Serversrecently
