Containers
After this page, you know why you should not use the container image of email-mcp on your own computer, and what the image is. A container is a way to run a program in its own closed space. An image is the package that holds the program, to run in a container.
Short version: for use on your own computer, do not use the container. Install the program instead (see Install email-mcp).
The container image is for testing and for building on, not for daily use. A hosted mode for many people (one server that many people use) is planned. It is not available. The tech docs page Local development explains how to build the image and try it.
Why the container does not work for local use
- No keychain. By default, email-mcp keeps its master key (the key that
protects the stored passwords) in the keychain of your operating system (its
password store). A container cannot reach the keychain of your computer.
Inside the container you must use a key file instead, with
EMAIL_MCP_KEK=file:<path>.EMAIL_MCP_KEKis an environment variable (a named setting that a program reads from its surroundings) that says where the master key is. Without it,servestops with an error about the keychain. See The master key. - 127.0.0.1 inside the container is not your computer. Every container has
its own network. Its loopback address (127.0.0.1) is reachable only from
inside that container (see the sources below). So
email-mcp serve --http 127.0.0.1:8765inside the container is a server that nothing outside the container can connect to. That is why the default command of the image isemail-mcp serve, which uses stdio (standard input and output) and needs no network. Local HTTP mode does not work inside a container. See Local HTTP mode. - Publishing the port does not help.
docker run -p 8765:8765forwards to the network interface of the container (the connection of the container to its network), not to its loopback address. And email-mcp refuses to listen on any address that is not a loopback address:serve --http 0.0.0.0:8765stops at once. This is on purpose: local HTTP mode has no TLS (Transport Layer Security: the encryption of a connection), so it must never be open to a network. - The web pages are not reachable either.
email-mcp setupand the approval links use the nameemail-mcp.localhost, which the server answers only on 127.0.0.1 inside the container. Your browser, outside the container, cannot open it.
What the image is
- By default, the image starts
/email-mcp serve: MCP (Model Context Protocol) over stdio. In the Dockerfile (the file that says how to build the image),ENTRYPOINTis/email-mcpandCMDisserve. An MCP client runs the image withdocker run -i(-ikeeps standard input open), as it would run a local binary. - The release workflow publishes it as
ghcr.io/emadmokhtar/email-mcp(the GitHub Container Registry) forlinux/amd64andlinux/arm64. The image has the same binary as the signed release archives, an SBOM (software bill of materials: a list of every module inside a binary) from Docker, and a GitHub build-provenance attestation (a signed record of which workflow built the image). The page Verifying a release shows how to verify it.
Sources
The statements about Docker on this page are checked against the Docker documentation, on 2026-11-06:
- “Networking overview”
(https://docs.docker.com/engine/network/): it says that
--dns=127.0.0.1refers to the container’s own loopback address. Point 2 rests on this. - “docker container run”
(https://docs.docker.com/reference/cli/docker/container/run/):
-ikeeps standard input open.