[Docker] Network binding to 127.0.0.1 prevents container access + Complete Docker setup guide

[georgy-agaev]

Problem

The MCP server binds to 127.0.0.1 when running in Docker, making it unreachable from the host machine.

Environment

• Docker version: 24.0.7
• OS: macOS 14.x
• penpot-mcp: latest (as of Dec 2024)

Root Cause

In penpot_mcp/server/mcp_server.py, the server uses:

uvicorn.run(..., host="127.0.0.1", ...)

When running in Docker, 127.0.0.1 refers to the container's loopback, not the host.

Error Symptoms

curl http://localhost:5001/sse
# curl: (56) Recv failure: Connection reset by peer

Proposed Solutions

Option 1: Make host configurable (Recommended)

import os
host = os.getenv("MCP_HOST", "127.0.0.1")
uvicorn.run(..., host=host, ...)

Option 2: Auto-detect Docker environment

import os
is_docker = os.path.exists('/.dockerenv')
host = "0.0.0.0" if is_docker else "127.0.0.1"

Workaround for Current Version

I've created a monkey-patch Dockerfile that works today:
https://gist.github.com/georgy-agaev/13e8852c999d219f9d9d8b02126eb7dc

Full Docker Setup Guide

I've documented a complete working setup including:

• Docker Compose configuration
• Penpot backend integration
• Claude Desktop configuration (both SSE and stdio modes)
• Troubleshooting steps

Would you like me to:

1. Submit a PR fixing the network binding issue?
2. Add Docker deployment documentation?
3. Add example Docker Compose files to the repository?

Happy to contribute any/all of these! 🚀