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/uplinkcrate/blob/main/mcp.env.example)):\n\n| Variable | Description | Default |\n|---|---|---|\n| `MCP_API_KEY` | Bootstrap key for MCP integrations and the outer dashboard/management gate; empty/unset reuses the stored key, generating one only when absent | Persisted or 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\nuplink_api_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\nMCP requests require a valid Bearer token. The bootstrap key remains supported; retrieve it first:\n\n```bash\nuplink_api_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 $uplink_api_key\"\n```\n\n**MCP endpoint (specific server):**\n\n```bash\ncurl http://localhost:3000/mcp/fetch \\\n -H \"Authorization: Bearer $uplink_api_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### Authentication and dashboard keys\n\nStandard self-hosted, JSON-backed root-URL deployments support dashboard-created MCP keys with native scopes and owner permissions. Copy the actual token when created, not its masked listing. A key limited to `fetch` uses `/mcp/fetch`; server-, group- and custom-limited keys cannot initialize global `/mcp`.\n\nUse `Authorization: Bearer `, or the configured native header for dashboard keys. The bootstrap key still works through standard `Authorization`. Conflicting credentials are rejected. Authentication cannot be disabled through the dashboard. Dashboard/static and management routes retain the bootstrap gate; protected management APIs additionally require native dashboard login/JWT.\n\nSessions are credential-bound. Reinitialize after a restart or permission change. Revocation affects later requests, not necessarily already accepted work/open responses. `mcp_manage --test fetch` performs an authenticated handshake and tools listing, not just a bare GET.\n\nUnsupported database/hosted/nonroot-base-path/skipAuth/advanced-auth/header modes retain observable bootstrap-only `legacy` behavior, or stop if startup is unsafe. Check `mcp_manage --status`. See [authentication, rotation and rollback details](https://github.com/hwdsl2/uplinkcrate/blob/main/docs/authentication.md).\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└── .Caddy.json # 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\nMCPHub 1.2.2 hashes existing dashboard API keys without changing their usable tokens or scopes. New tokens are shown only once. Preserve the entire volume, including any `mcp_settings.json.credentials.key` file. Older upstream versions cannot interpret hashed keys. Enabled hash-only keys can also break MCP requests in 1.0.38 even with native Bearer authentication disabled; review the [rollback limits](https://github.com/hwdsl2/uplinkcrate/blob/main/docs/authentication.md#upgrade-and-rollback) before downgrading.\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 UplinkCrate 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 UplinkCrate container from your reverse proxy:\n\n- **`mcp:3000`** — if your reverse proxy runs as a container in the **same Docker network** as UplinkCrate (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\nUplinkCrate 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 SpeakCrate, EmbedCrate, GatewayCrate, InferCrate, ParseCrate, and UplinkCrate, see [Self-Hosted AI Stack](https://github.com/hwdsl2/self-hosted-ai-stack).\n\n**Related AI services:**\n\n- **Voice:** [ScribeCrate](https://github.com/hwdsl2/scribecrate), [SpeakCrate](https://github.com/hwdsl2/speakcrate)\n- **Documents & search:** [ParseCrate](https://github.com/hwdsl2/parsecrate), [EmbedCrate](https://github.com/hwdsl2/embedcrate)\n- **Models & gateways:** [InferCrate](https://github.com/hwdsl2/infercrate), [GatewayCrate](https://github.com/hwdsl2/gatewaycrate)\n\n**Connect UplinkCrate to GatewayCrate:**\n\nFor GatewayCrate or another compatible LiteLLM deployment, add UplinkCrate as an MCP tool source:\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/uplinkcrate#usage-counts).\n\n## Technical details\n\n- Base image: `samanhappy/mcphub` (Python 3.13 + Node.js 22)\n- Authentication: [Caddy](https://caddyserver.com) plus an in-process mandatory MCP policy; legacy mode retains the bootstrap-only proxy\n- Gateway: [MCPHub](https://github.com/samanhappy/mcphub) (multi-server MCP hub)\n- MCPHub internal port: `3001` (bound to IPv4 loopback; 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",{"_293":11,"_294":295},"enabled","rules",[296],".*","is_automated","permissions",{"_300":21,"_301":11,"_302":11},"read","write","admin","user","storage_size",974106722,"isOrg","reponame","tag","sha256:ed45212e667975f58beb37c6eb27d005013f2bee6ba8ee5ed134f7bc704af394","canDeleteTags","isHubSbxKitsEnabled","currentTab","tagAttestations","displaySecurityMetadata","showSbxLogoOverride","showSbxAgenticPlatformBadge","routes/_layout.layers.$namespace.$reponame.$tag.(images).($imageUrlDigest)._index",{"_26":27,"_246":-7,"_244":-7,"_245":-7,"_28":319,"_34":309,"_322":-7,"_323":11},{"_30":31,"_32":33,"_34":35,"_36":37,"_38":39,"_40":320,"_60":61,"_62":33,"_63":64,"_65":66,"_67":68,"_69":70,"_71":49,"_72":61,"_73":58,"_74":21},[321],{"_43":44,"_34":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":47,"_55":-5,"_56":37,"_57":58,"_59":-5},"imageWithLayers","hasPermissionToViewRepoSettings","actionData","errors"]

hwdsl2/mcp-gateway:latest-amd64