Add Docker usage documentation

Users need to know how to run the CLI via Docker, including config
mounting, env vars, and the limitations around stdio servers and OAuth.

Added Docker as an install option in the README and getting-started
guide, plus a dedicated howto page covering aliases, env-file, piping,
version pinning, and what doesn't work in containers.

Signed-off-by: Avelino <31996+avelino@users.noreply.github.com>

Author: avelino

README.md

@@ -28,6 +28,10 @@ Output is always JSON. Pipe it, `jq` it, script it.
 # Homebrew (macOS and Linux)
 brew install avelino/mcp/mcp
 
+# Docker
+docker pull ghcr.io/avelino/mcp
+alias mcp='docker run --rm -v ~/.config/mcp:/root/.config/mcp ghcr.io/avelino/mcp'
+
 # Pre-built binary from GitHub Releases
 # Download the latest from https://github.com/avelino/mcp/releases
 
@@ -130,6 +134,36 @@ If you don't pass JSON arguments on the command line, `mcp` reads from stdin:
 echo '{"query": "is:unresolved"}' | mcp sentry search_issues
 ```
 
+## Docker
+
+The CLI is available as a multi-arch Docker image (amd64/arm64):
+
+```bash
+# Run directly
+docker run --rm -v ~/.config/mcp:/root/.config/mcp ghcr.io/avelino/mcp --list
+
+# Call a tool
+docker run --rm -v ~/.config/mcp:/root/.config/mcp ghcr.io/avelino/mcp sentry search_issues '{"query": "is:unresolved"}'
+
+# Pass environment variables for servers that need them
+docker run --rm \
+  -v ~/.config/mcp:/root/.config/mcp \
+  -e GITHUB_TOKEN \
+  ghcr.io/avelino/mcp github search_repositories '{"query": "mcp"}'
+
+# Use an alias for convenience
+alias mcp='docker run --rm -v ~/.config/mcp:/root/.config/mcp ghcr.io/avelino/mcp'
+mcp sentry --list
+```
+
+Available tags:
+
+| Tag | Description |
+|---|---|
+| `latest` | Latest stable release |
+| `x.y.z` | Pinned version |
+| `beta` | Latest build from main branch |
+
 ## Environment variables
 
 | Variable | Description |

docs/SUMMARY.md

@@ -17,6 +17,7 @@
 
 ## How-to
 
+* [Docker](howto/docker.md)
 * [Supported services](howto/services.md)
 * [Troubleshooting](howto/troubleshooting.md)
 

docs/getting-started.md

@@ -19,6 +19,24 @@ chmod +x mcp-*
 sudo mv mcp-* /usr/local/bin/mcp
 ```
 
+**Docker:**
+
+```bash
+docker pull ghcr.io/avelino/mcp
+```
+
+To use it like a native command, create an alias:
+
+```bash
+alias mcp='docker run --rm -v ~/.config/mcp:/root/.config/mcp ghcr.io/avelino/mcp'
+```
+
+Add the alias to your shell profile (`~/.bashrc`, `~/.zshrc`, or `~/.config/fish/config.fish`) to make it permanent. If your servers need environment variables (API tokens, etc.), pass them with `-e`:
+
+```bash
+alias mcp='docker run --rm -v ~/.config/mcp:/root/.config/mcp -e GITHUB_TOKEN ghcr.io/avelino/mcp'
+```
+
 **From source (requires Rust):**
 
 ```bash

docs/howto/docker.md

@@ -0,0 +1,106 @@
+# Running with Docker
+
+The `mcp` CLI is available as a multi-arch Docker image (amd64/arm64) on GitHub Container Registry.
+
+## Pull the image
+
+```bash
+docker pull ghcr.io/avelino/mcp
+```
+
+## Available tags
+
+| Tag | Description |
+|---|---|
+| `latest` | Latest stable release |
+| `x.y.z` | Pinned version (e.g. `0.1.0`) |
+| `beta` | Latest build from main branch |
+
+## Basic usage
+
+The CLI runs as the container entrypoint. Pass arguments directly:
+
+```bash
+docker run --rm ghcr.io/avelino/mcp --help
+docker run --rm ghcr.io/avelino/mcp search github
+```
+
+## Using your config
+
+Mount your local config directory so the container can access your server definitions:
+
+```bash
+docker run --rm \
+  -v ~/.config/mcp:/root/.config/mcp \
+  ghcr.io/avelino/mcp --list
+```
+
+## Passing environment variables
+
+Servers that need API tokens or other secrets require environment variables. Pass them with `-e`:
+
+```bash
+docker run --rm \
+  -v ~/.config/mcp:/root/.config/mcp \
+  -e GITHUB_TOKEN \
+  -e SLACK_TOKEN \
+  ghcr.io/avelino/mcp github list_repositories '{"query": "mcp"}'
+```
+
+You can also use an env file:
+
+```bash
+# .env
+GITHUB_TOKEN=ghp_xxxx
+SLACK_TOKEN=xoxb-xxxx
+```
+
+```bash
+docker run --rm \
+  -v ~/.config/mcp:/root/.config/mcp \
+  --env-file .env \
+  ghcr.io/avelino/mcp sentry search_issues '{"query": "is:unresolved"}'
+```
+
+## Shell alias
+
+For day-to-day use, create an alias so `mcp` works like a native command:
+
+```bash
+# bash / zsh — add to ~/.bashrc or ~/.zshrc
+alias mcp='docker run --rm -v ~/.config/mcp:/root/.config/mcp --env-file ~/.config/mcp/.env ghcr.io/avelino/mcp'
+
+# fish — add to ~/.config/fish/config.fish
+alias mcp 'docker run --rm -v ~/.config/mcp:/root/.config/mcp --env-file ~/.config/mcp/.env ghcr.io/avelino/mcp'
+```
+
+Then use it normally:
+
+```bash
+mcp --list
+mcp sentry search_issues '{"query": "is:unresolved"}'
+mcp search filesystem
+```
+
+## Piping JSON
+
+Pipe input via stdin with `-i` (Docker's interactive flag):
+
+```bash
+echo '{"query": "is:unresolved"}' | docker run --rm -i \
+  -v ~/.config/mcp:/root/.config/mcp \
+  ghcr.io/avelino/mcp sentry search_issues
+```
+
+## Pinning a version
+
+For CI/CD or reproducible environments, pin to a specific version:
+
+```bash
+docker run --rm ghcr.io/avelino/mcp:0.1.0 --help
+```
+
+## Limitations
+
+- **Stdio servers only work if the runtime is available inside the container.** The default image includes only the `mcp` binary and `ca-certificates`. Servers that require `npx`, `python`, or other runtimes won't work unless you build a custom image. HTTP servers (configured with `url`) work out of the box.
+- **OAuth browser flow doesn't work in Docker.** For HTTP servers that need OAuth, run `mcp add <server>` on your host first to complete authentication, then mount the config directory (which includes `auth.json`).