Self-hosted VPN & networking projects

\n\n- [Setup IPsec VPN](https://github.com/hwdsl2/setup-ipsec-vpn)\n- [IPsec VPN on Docker](https://github.com/hwdsl2/docker-ipsec-vpn-server)\n- [WireGuard](https://github.com/hwdsl2/docker-wireguard)\n- [OpenVPN](https://github.com/hwdsl2/docker-openvpn)\n- [Headscale](https://github.com/hwdsl2/docker-headscale)\n\n

\n\n## Requirements\n\n- A Linux server (local or cloud) with Docker installed\n- At least 512 MB of available RAM\n- TCP port 3000 (or your configured port) accessible\n\n## Download\n\nGet the trusted build from the [Docker Hub registry](https://hub.docker.com/r/hwdsl2/mcp-gateway/):\n\n```bash\ndocker pull hwdsl2/mcp-gateway\n```\n\nAlternatively, you may download from [Quay.io](https://quay.io/repository/hwdsl2/mcp-gateway):\n\n```bash\ndocker pull quay.io/hwdsl2/mcp-gateway\ndocker image tag quay.io/hwdsl2/mcp-gateway hwdsl2/mcp-gateway\n```\n\nSupported platforms: `linux/amd64` and `linux/arm64`.\n\n## Environment variables\n\nAll variables are optional. If not set, secure defaults are used automatically.\n\nThis Docker image uses the following variables, that can be declared in an `env` file (see [example](https://github.com/hwdsl2/docker-mcp-gateway/blob/main/mcp.env.example)):\n\n| Variable | Description | Default |\n|---|---|---|\n| `MCP_API_KEY` | API key for authenticating requests (auto-generated if not set) | Auto-generated |\n| `MCP_PORT` | TCP port for the gateway (1–65535) | `3000` |\n| `MCP_HOST` | Hostname or IP shown in startup info and `--showkey` output | Auto-detected |\n| `MCP_SERVERS` | Comma-separated list of MCP servers to enable | `fetch` |\n| `MCP_ADMIN_PASSWORD` | Password for the MCPHub dashboard admin account (auto-generated on first start if not set) | Auto-generated |\n| `MCP_DISABLE_USAGE_COUNTS` | Set to `1` to disable anonymous aggregate usage counts. | *(not set)* |\n\n**Note:** In your `env` file, you may enclose values in single quotes, e.g. `VAR='value'`. Do not add spaces around `=`. If you change `MCP_PORT`, update the `-p` flag in the `docker run` command accordingly.\n\nExample using an `env` file:\n\n```bash\ncp mcp.env.example mcp.env\n# Edit mcp.env and set your values, then:\ndocker run \\\n --name mcp \\\n --restart=always \\\n -v mcp-data:/var/lib/mcp \\\n -v ./mcp.env:/mcp.env:ro \\\n -p 3000:3000/tcp \\\n -d hwdsl2/mcp-gateway\n```\n\n### Available MCP servers\n\nEnable servers by listing them in `MCP_SERVERS` (comma-separated):\n\n| Server | Required config | Description |\n|---|---|---|\n| `fetch` | — | Fetch URLs and extract content |\n| `filesystem` | `MCP_FILESYSTEM_DIRS` | Read/write files in allowed directories |\n| `github` | `MCP_GITHUB_TOKEN` | GitHub API access (repos, issues, PRs) |\n| `brave-search` | `MCP_BRAVE_API_KEY` | Web search via Brave Search API |\n| `git` | `MCP_GIT_REPO` | Git repository tools (status, diff, commit, log) |\n| `postgres` | `MCP_POSTGRES_URL` | Query PostgreSQL databases |\n| `memory` | — | Knowledge graph / persistent memory |\n| `sequential-thinking` | — | Structured thinking and reasoning |\n\n**Example:**\n\n```bash\n# Enable filesystem, fetch, and GitHub servers\nMCP_SERVERS=filesystem,fetch,github\nMCP_FILESYSTEM_DIRS=/data/docs,/data/projects\nMCP_GITHUB_TOKEN=ghp_your_token_here\n```\n\nFor the `filesystem` server, bind-mount host directories into the container:\n\n```bash\ndocker run \\\n --name mcp \\\n --restart=always \\\n -v mcp-data:/var/lib/mcp \\\n -v ./mcp.env:/mcp.env:ro \\\n -v /home/user/documents:/data/docs:ro \\\n -v /home/user/projects:/data/projects \\\n -p 3000:3000/tcp \\\n -d hwdsl2/mcp-gateway\n```\n\nFor the `git` server, bind-mount the repository into the container and set `MCP_GIT_REPO`:\n\n```bash\nMCP_SERVERS=git\nMCP_GIT_REPO=/repo\n```\n\n```bash\ndocker run \\\n --name mcp \\\n --restart=always \\\n -v mcp-data:/var/lib/mcp \\\n -v ./mcp.env:/mcp.env:ro \\\n -v /home/user/myrepo:/repo \\\n -p 3000:3000/tcp \\\n -d hwdsl2/mcp-gateway\n```\n\n## Managing MCP servers\n\nUse `docker exec` to manage the gateway with the `mcp_manage` helper script.\n\n**List enabled servers:**\n\n```bash\ndocker exec mcp mcp_manage --list\n```\n\n**Test a specific server:**\n\n```bash\ndocker exec mcp mcp_manage --test fetch\ndocker exec mcp mcp_manage --test github\n```\n\n**Show gateway status:**\n\n```bash\ndocker exec mcp mcp_manage --status\n```\n\n**Show the API key:**\n\n```bash\ndocker exec mcp mcp_manage --showkey\n```\n\n**Get the API key** (machine-readable, for use in scripts):\n\n```bash\nMCP_KEY=$(docker exec mcp mcp_manage --getkey)\n```\n\n**Add or remove servers at runtime:**\n\nUse the MCPHub dashboard at `http://:3000/` to add, configure, or remove MCP servers without restarting the container. Changes are saved to the persistent volume and survive restarts.\n\n> **Note:** `MCP_SERVERS` only applies on the **first run** when `mcp_settings.json` is created. After that, the dashboard is the way to manage servers. Resetting the file this way replaces any server configuration saved through the dashboard. To re-apply `MCP_SERVERS` from scratch, remove the config file and restart:\n> ```bash\n> docker exec mcp rm /var/lib/mcp/mcp_settings.json\n> docker restart mcp\n> ```\n\n## Using the API\n\nAll API requests require a Bearer token. Retrieve the API key first:\n\n```bash\nMCP_KEY=$(docker exec mcp mcp_manage --getkey)\n```\n\n**MCP endpoint (all enabled servers):**\n\n```bash\ncurl http://localhost:3000/mcp \\\n -H \"Authorization: Bearer $MCP_KEY\"\n```\n\n**MCP endpoint (specific server):**\n\n```bash\ncurl http://localhost:3000/mcp/fetch \\\n -H \"Authorization: Bearer $MCP_KEY\"\n```\n\n**Dashboard** (web UI):\n\nOpen `http://localhost:3000/` in a browser with `Authorization: Bearer `, or use a client that supports header injection.\n\n**Health check** (no auth required):\n\n```bash\ncurl http://localhost:3000/health\n```\n\n### Connecting AI clients\n\n**Cline (VS Code)** — in Cline's MCP settings:\n\n```json\n{\n \"mcpServers\": {\n \"gateway\": {\n \"url\": \"http://localhost:3000/mcp\",\n \"transport\": \"streamable-http\",\n \"headers\": {\n \"Authorization\": \"Bearer \"\n }\n }\n }\n}\n```\n\n**Claude Desktop** — in `claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"gateway\": {\n \"url\": \"http://localhost:3000/mcp\",\n \"transport\": \"streamable-http\",\n \"headers\": {\n \"Authorization\": \"Bearer \"\n }\n }\n }\n}\n```\n\n## Persistent data\n\nAll gateway data is stored in the Docker volume (`/var/lib/mcp` inside the container):\n\n```\n/var/lib/mcp/\n├── mcp_settings.json # Generated MCPHub configuration\n├── .api_key # API key (auto-generated, or synced from MCP_API_KEY)\n├── .initialized # First-run marker\n├── .port # Saved port (used by mcp_manage)\n├── .servers # Enabled servers list (used by mcp_manage)\n└── .Caddyfile # Generated Caddy config (auth proxy)\n```\n\n`mcp_settings.json` is generated from `MCP_SERVERS` on first run only. Subsequent restarts reuse the existing file, preserving any changes made via the dashboard.\n\nBack up the Docker volume to preserve your configuration and API key.\n\n## Using docker-compose\n\n```bash\ncp mcp.env.example mcp.env\n# Edit mcp.env and set your values, then:\ndocker compose up -d\ndocker logs mcp\n```\n\nExample `docker-compose.yml` (already included):\n\n```yaml\nservices:\n mcp:\n image: hwdsl2/mcp-gateway\n container_name: mcp\n restart: always\n ports:\n - \"3000:3000/tcp\" # For a host-based reverse proxy, change to \"127.0.0.1:3000:3000/tcp\"\n volumes:\n - mcp-data:/var/lib/mcp\n - ./mcp.env:/mcp.env:ro\n # Mount host directories for the filesystem MCP server (optional):\n # - /path/to/docs:/data/docs:ro\n # - /path/to/code:/data/code:ro\n\nvolumes:\n mcp-data:\n name: mcp-data\n```\n\n**Note:** For internet-facing deployments, use a [reverse proxy](#using-a-reverse-proxy) to add HTTPS. Also change `\"3000:3000/tcp\"` to `\"127.0.0.1:3000:3000/tcp\"` in `docker-compose.yml`, to prevent direct access to the unencrypted port.\n\n## Using a reverse proxy\n\nFor internet-facing deployments, place a reverse proxy in front of MCP Gateway to handle HTTPS termination. The server works without HTTPS on a local or trusted network, but HTTPS is recommended when the API endpoint is exposed to the internet.\n\nUse one of the following addresses to reach the MCP Gateway container from your reverse proxy:\n\n- **`mcp:3000`** — if your reverse proxy runs as a container in the **same Docker network** as MCP Gateway (e.g. defined in the same `docker-compose.yml`).\n- **`127.0.0.1:3000`** — if your reverse proxy runs **on the host** and port `3000` is published (the default `docker-compose.yml` publishes it).\n\n**Note:** The `Authorization: Bearer` header passes through reverse proxies automatically — no special configuration needed.\n\n**Example with [Caddy](https://caddyserver.com/docs/) ([Docker image](https://hub.docker.com/_/caddy))** (automatic TLS via Let's Encrypt, reverse proxy in the same Docker network):\n\n`Caddyfile`:\n```\nmcp.example.com {\n reverse_proxy mcp:3000\n}\n```\n\n**Example with nginx** (reverse proxy on the host):\n\n```nginx\nserver {\n listen 443 ssl;\n server_name mcp.example.com;\n\n ssl_certificate /path/to/cert.pem;\n ssl_certificate_key /path/to/key.pem;\n\n location / {\n proxy_pass http://127.0.0.1:3000;\n proxy_set_header Host $host;\n proxy_set_header X-Real-IP $remote_addr;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n proxy_http_version 1.1; # required for SSE and WebSocket\n proxy_read_timeout 300s;\n proxy_buffering off;\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n }\n}\n```\n\nAfter setting up a reverse proxy, set `MCP_HOST=mcp.example.com` in your `env` file so that the correct endpoint URL is shown in the startup logs and `mcp_manage --showkey` output.\n\n## Update Docker image\n\nTo update the Docker image and container, first [download](#download) the latest version:\n\n```bash\ndocker pull hwdsl2/mcp-gateway\n```\n\nIf the Docker image is already up to date, you should see:\n\n```\nStatus: Image is up to date for hwdsl2/mcp-gateway:latest\n```\n\nOtherwise, it will download the latest version. Remove and re-create the container:\n\n```bash\ndocker rm -f mcp\n# Then re-run the docker run command from Quick start with the same volume.\n```\n\nYour configuration and API key are preserved in the `mcp-data` volume.\n\n## Using with other AI services\n\nMCP Gateway can be used as the MCP tool gateway in a broader self-hosted AI setup.\n\nFor full and lightweight Docker Compose stacks, manual `docker run` examples, and voice/RAG/MCP pipeline examples with Kokoro, Embeddings, LiteLLM, Ollama, Docling, and MCP Gateway, see [Self-Hosted AI Stack](https://github.com/hwdsl2/self-hosted-ai-stack).\n\n**Connect MCP Gateway to LiteLLM:**\n\n```yaml\n# In your LiteLLM config, add the MCP gateway as a tool source:\nmcp_servers:\n - url: http://mcp:3000/mcp\n transport: http\n headers:\n Authorization: \"Bearer \"\n```\n\n## Usage counts\n\nSee [Usage counts](https://github.com/hwdsl2/docker-mcp-gateway#usage-counts).\n\n## Technical details\n\n- Base image: `samanhappy/mcphub` (Python 3.13 + Node.js 22)\n- Auth proxy: [Caddy](https://caddyserver.com) (always active, enforces Bearer token auth)\n- Gateway: [MCPHub](https://github.com/samanhappy/mcphub) (multi-server MCP hub)\n- MCPHub internal port: `3001` (not published; Caddy proxies from `MCP_PORT`)\n- Data directory: `/var/lib/mcp` (Docker volume)\n- Gateway API: `http://localhost:3000` (or your configured port)\n- MCP endpoint: `http://localhost:3000/mcp`\n- Multi-arch: `linux/amd64`, `linux/arm64`\n\n## License\n\n**Note:** The software components inside the pre-built image (such as MCPHub, Caddy, and their dependencies) are under the respective licenses chosen by their respective copyright holders. As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.\n\nCopyright (C) 2026 Lin Song \nThis work is licensed under the [MIT License](https://opensource.org/licenses/MIT).\n\n**MCPHub** is Copyright (C) 2025 samanhappy, and is distributed under the [Apache License 2.0](https://github.com/samanhappy/mcphub/blob/main/LICENSE).\n\n**Caddy** is Copyright (C) 2015 Matthew Holt and The Caddy Authors, and is distributed under the [Apache License 2.0](https://github.com/caddyserver/caddy/blob/master/LICENSE).\n\nThis project is an independent Docker setup for MCPHub and is not affiliated with, endorsed by, or sponsored by MCPHub.","has_starred","hub_user","immutable_tags_settings",{"_276":11,"_277":278},"enabled","rules",[279],".*","is_automated","permissions",{"_283":17,"_284":11,"_285":11},"read","write","admin","user","storage_size",975187796,"isOrg","reponame","tag","sha256:974f66475af2677e2e34b9c7dc8da7d095a499e3b58821c16c409d1eb237352f","canDeleteTags","isHubSbxKitsEnabled","currentTab","tagAttestations","displaySecurityMetadata","showSbxLogoOverride","routes/_layout.layers.$namespace.$reponame.$tag.(images).($imageUrlDigest)._index",{"_23":24,"_229":-7,"_227":-7,"_228":-7,"_25":301,"_31":292,"_304":-7,"_305":11},{"_27":28,"_29":30,"_31":32,"_33":34,"_35":36,"_37":302,"_57":58,"_59":30,"_60":61,"_62":63,"_64":65,"_66":67,"_68":46,"_69":58,"_70":55,"_71":17},[303],{"_40":41,"_31":42,"_43":44,"_45":46,"_47":48,"_49":50,"_51":44,"_52":-5,"_53":34,"_54":55,"_56":-5},"imageWithLayers","hasPermissionToViewRepoSettings","actionData","errors"]

hwdsl2/mcp-gateway:latest-amd64