From 48b7b6f68210d9152ff33b79230430ebaf36ff03 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 31 May 2026 11:57:33 +0000 Subject: [PATCH 1/3] docs: clarify .env handling in Docker run, document recommended command Combine the persistent home-directory example with the named cache volumes to match common usage, and add a table explaining why .env is referenced twice (--env-file injects vars; -v mounts the file for MCP_ENV_FILE and the Secrets UI). Note both flags take the local host path, that the file must exist, and that MCP_ENV_FILE already defaults to /app/.env in the image. --- README.md | 41 +++++++++++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index b590bbb..53cb1af 100755 --- a/README.md +++ b/README.md @@ -250,26 +250,55 @@ Follow logs with `docker logs -f mcpproxy`; stop the container with `docker stop > `handlers/` is part of the image — no mount required. **Run from a persistent home directory** — store tools and secrets in `~/.mcpproxy` so -you can run the image from any working directory and the web UI can read and write `.env`: +you can run the image from any working directory and the web UI can read and write `.env`. +This is the recommended day-to-day command — it combines the persistent home directory +with the named cache volumes: ```bash # First time only — create the directory and an empty .env mkdir -p ~/.mcpproxy/tools touch ~/.mcpproxy/.env -docker run -d \ +docker run -d --rm \ -p 8888:8888 -p 8889:8889 \ --env-file "$HOME/.mcpproxy/.env" \ - -e MCP_ENV_FILE=/app/.env \ -v "$HOME/.mcpproxy/tools:/app/tools" \ -v "$HOME/.mcpproxy/.env:/app/.env" \ + -v mcpproxy-files:/app/files \ + -v mcpproxy-repos:/app/repos \ + -v mcpproxy-cache:/root/.cache \ + -v mcpproxy-npm:/root/.npm \ + -v mcpproxy-uv-tools:/root/.local/share/uv \ + -v mcpproxy-mcp-auth:/app/.mcp-auth \ --name mcpproxy \ ghcr.io/billjr99/mcpproxy:latest ``` -Two things differ from the minimal command: -- `--env-file` injects secrets as environment variables at startup; Docker does **not** expand `~` inside double quotes, so `$HOME` is used instead. -- `-v "$HOME/.mcpproxy/.env:/app/.env"` + `-e MCP_ENV_FILE=/app/.env` also mount the file itself into the container so the web UI's **🔑 Secrets** panel can read and write values without leaving the browser. +#### `.env`: the two flags it needs, and why + +The `.env` file is referenced **twice** above, and each reference does a different job — +both point at the **same local file** on your host: + +| Flag | Local path → target | What it does | +| ---- | ------------------- | ------------ | +| `--env-file "$HOME/.mcpproxy/.env"` | host file, parsed by Docker | Reads the file and injects each `KEY=value` line as an **environment variable** in the container at startup. | +| `-v "$HOME/.mcpproxy/.env:/app/.env"` | host file → `/app/.env` | Bind-**mounts the file itself** into the container so the proxy can read it directly (via `MCP_ENV_FILE`, which the image defaults to `/app/.env`) and pass values to the MCP tool subprocesses it spawns. It also lets the web UI's **🔑 Secrets** panel read and write values live. | + +Notes: +- In **both** flags, the path is your **local** `.env` on the host — `--env-file` takes the + host path directly, and the **left** side of `-v host:container` is the host path while + the **right** side (`/app/.env`) is where it appears inside the container. +- The file must already exist (hence the `touch` above). If it's missing, `--env-file` + errors that the file isn't found, and the `-v` mount would create a *directory* named + `.env` instead. +- Docker does **not** expand `~` inside double quotes, so use `$HOME` instead. +- You don't need `-e MCP_ENV_FILE=/app/.env` — the image already defaults `MCP_ENV_FILE` + to `/app/.env`. Pass it explicitly only if you mount the file somewhere else. + +The `mcpproxy-mcp-auth` volume holds the OAuth token cache for `mcp-remote` bridge +providers (e.g. the official Asana MCP); persist it and you authorize once. Map the OAuth +callback port (`-p 3334:3334`) the first time you authorize. Omit any volume you don't need +— each falls back to the container's ephemeral writable layer. Available tags: From 8ba983d03892d921beac6242d98bcf350751da4e Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 31 May 2026 11:58:56 +0000 Subject: [PATCH 2/3] docs: drop --rm from recommended Docker run command Keep the container around across stops/reboots; the named volumes already handle persistence. MCP_ENV_FILE need not be passed explicitly since the image defaults it to /app/.env. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 53cb1af..19a9440 100755 --- a/README.md +++ b/README.md @@ -259,7 +259,7 @@ with the named cache volumes: mkdir -p ~/.mcpproxy/tools touch ~/.mcpproxy/.env -docker run -d --rm \ +docker run -d \ -p 8888:8888 -p 8889:8889 \ --env-file "$HOME/.mcpproxy/.env" \ -v "$HOME/.mcpproxy/tools:/app/tools" \ From f4303532b5bd6f9ee2740a4d4003b1f0de26ea14 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 31 May 2026 11:59:40 +0000 Subject: [PATCH 3/3] docs: show MCP_ENV_FILE explicitly in Docker example for discoverability Include -e MCP_ENV_FILE=/app/.env in the recommended run command so users know the setting exists, and note that it's optional since the image already defaults it. --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 19a9440..cdcfa9d 100755 --- a/README.md +++ b/README.md @@ -262,6 +262,7 @@ touch ~/.mcpproxy/.env docker run -d \ -p 8888:8888 -p 8889:8889 \ --env-file "$HOME/.mcpproxy/.env" \ + -e MCP_ENV_FILE=/app/.env \ -v "$HOME/.mcpproxy/tools:/app/tools" \ -v "$HOME/.mcpproxy/.env:/app/.env" \ -v mcpproxy-files:/app/files \ @@ -292,8 +293,9 @@ Notes: errors that the file isn't found, and the `-v` mount would create a *directory* named `.env` instead. - Docker does **not** expand `~` inside double quotes, so use `$HOME` instead. -- You don't need `-e MCP_ENV_FILE=/app/.env` — the image already defaults `MCP_ENV_FILE` - to `/app/.env`. Pass it explicitly only if you mount the file somewhere else. +- `-e MCP_ENV_FILE=/app/.env` is shown for clarity, but it's optional — the image already + defaults `MCP_ENV_FILE` to `/app/.env`. You only *need* it if you mount the file somewhere + else. The `mcpproxy-mcp-auth` volume holds the OAuth token cache for `mcp-remote` bridge providers (e.g. the official Asana MCP); persist it and you authorize once. Map the OAuth