Deploying MCP Servers via Docker Container: A Complete Guide to the Wordle MCP Server

You can deploy the Wordle MCP server via Docker by pulling the ghcr.io/cr2007/mcp-wordle-python:latest image and configuring your MCP client to run the container with --rm -i --init flags, enabling standardized Model Context Protocol communication without installing Python dependencies locally.

The cr2007/mcp-wordle-python repository demonstrates a production-ready approach to deploying MCP servers via Docker container, packaging a lightweight FastMCP application that fetches daily Wordle solutions. This implementation uses a multistage build process to minimize image size while ensuring consistent runtime behavior across different environments. Understanding this deployment pattern provides a blueprint for containerizing any Model Context Protocol server for use with AI assistants like Claude Desktop.

Understanding the Wordle MCP Server Architecture

FastMCP Server Implementation

In src/mcp_wordle/main.py, the server initializes a FastMCP instance that handles incoming MCP calls and routes them to registered tools. The core setup creates a named server instance:

from fastmcp import FastMCP

mcp = FastMCP("WordleMCP")

The get_wordle_solution Tool

The server exposes a single asynchronous tool decorated with @mcp.tool() that queries the New York Times Wordle API. The implementation in src/mcp_wordle/main.py defines the function signature and API interaction:

@mcp.tool(
    name="get_wordle_solution",
    description=(
        "Fetches the Wordle of a particular date provided "
        "between 2021-05-19 to 23 days future"
    ),
    annotations={"readOnlyHint": True},
)
async def get_wordle_data(target_date: str = date.today().isoformat()) -> Union[WordleAPIData, WordleError]:
    url = f"https://www.nytimes.com/svc/wordle/v2/{target_date}.json"
    return requests.get(url, timeout=300).json()

When the container starts, mcp.run() launches the MCP server and begins listening for requests.

Docker Multistage Build Strategy

The Dockerfile implements a multistage build that separates compilation from runtime, significantly reducing the final image size compared to single-stage builds.

Builder Stage with UV

The first stage uses the ghcr.io/astral-sh/uv:0.7-python3.10-bookworm-slim image to compile dependencies. The UV package manager installs project requirements via uv sync, creating a fully resolved virtual environment in /app according to the specifications in pyproject.toml.

Production Runtime Stage

The final stage copies only the compiled artifacts into a minimal python:3.10-slim-bookworm image. The pyproject.toml defines the console script entry point mcp-wordle, which the Dockerfile sets as the container's startup command:

ENTRYPOINT ["mcp-wordle"]

This approach excludes build tools from the production image, resulting in a container that contains only the Python runtime and the compiled application code.

Step-by-Step Docker Deployment

Pulling the Prebuilt Image

Retrieve the latest production image from the GitHub Container Registry:

docker pull ghcr.io/cr2007/mcp-wordle-python:latest

This command downloads the optimized image built from the multistage Dockerfile, containing all necessary dependencies pre-installed.

Configuring MCP Client Settings

Add the following configuration to your MCP client (such as Claude Desktop or another AI assistant that supports MCP):

{
  "mcpServers": {
    "Wordle MCP (Python)": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--init",
        "-e",
        "DOCKER_CONTAINER=true",
        "ghcr.io/cr2007/mcp-wordle-python:latest"
      ]
    }
  }
}

The flags ensure proper operation: --rm cleans up the container after exit, -i keeps STDIN open for MCP communication, and --init handles signal forwarding correctly. The DOCKER_CONTAINER=true environment variable allows the application to detect its runtime context if needed.

Testing the Deployment

Once connected, request a Wordle solution by calling the registered tool:

{
  "tool": "get_wordle_solution",
  "parameters": { "target_date": "2024-02-27" }
}

The server returns structured JSON containing the solution:

{
  "id": 1234,
  "solution": "TRACE",
  "print_date": "2024-02-27",
  "days_since_launch": 1020,
  "editor": "The New York Times"
}

If the requested date falls outside the valid range (2021-05-19 to 23 days in the future), the API returns an error object as defined in the WordleError type.

Summary

• The Wordle MCP server provides a complete example of deploying MCP servers via Docker container using FastMCP and multistage builds.
• The multistage Dockerfile compiles dependencies with UV in a builder stage, then copies only the runtime virtual environment to a minimal Python image.
• Configuration requires adding a Docker run command with --rm -i --init flags to your MCP client settings, pointing to ghcr.io/cr2007/mcp-wordle-python:latest.
• The server exposes the get_wordle_solution tool in src/mcp_wordle/main.py, which queries the New York Times Wordle API and returns daily puzzle solutions.
• This deployment pattern ensures environment consistency and eliminates local Python dependency management for end users.

Frequently Asked Questions

What is the advantage of using Docker for MCP servers?

Docker containers encapsulate the Python runtime, dependencies, and application code into a single immutable artifact. This eliminates "works on my machine" issues and allows AI assistants to invoke MCP tools without requiring users to install Python, UV, or any project-specific packages locally.

How does the multistage build reduce image size?

The multistage build separates the compilation environment (which includes build tools and the UV package manager) from the runtime environment. Only the compiled virtual environment from /app is copied to the final python:3.10-slim-bookworm image, excluding development dependencies and build artifacts that would otherwise increase the container size.

Can I modify the Wordle MCP server before deploying?

Yes, you can clone the cr2007/mcp-wordle-python repository, modify the code in src/mcp_wordle/main.py or adjust dependencies in pyproject.toml, then build a custom image using docker build -t my-wordle-mcp .. The multistage Dockerfile will automatically compile your changes using the same UV-based build process.

What MCP clients support Docker-based servers?

Most modern MCP clients including Claude Desktop, Cursor, and other AI assistants that implement the Model Context Protocol specification support Docker-based servers. You configure them by providing the docker run command and arguments in their MCP server configuration files, exactly as shown in the deployment examples above.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}