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

> Deploy Wordle MCP servers using Docker. Easily set up standardized Model Context Protocol communication without local Python dependencies. Get the complete guide for Dockerized MCP server deployment.

- Repository: [CSK/mcp-wordle-python](https://github.com/cr2007/mcp-wordle-python)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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`](https://github.com/cr2007/mcp-wordle-python/blob/main/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:

```python
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`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py) defines the function signature and API interaction:

```python
@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`](https://github.com/cr2007/mcp-wordle-python/blob/main/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`](https://github.com/cr2007/mcp-wordle-python/blob/main/pyproject.toml) defines the console script entry point `mcp-wordle`, which the Dockerfile sets as the container's startup command:

```dockerfile
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:

```bash
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):

```json
{
  "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:

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

```

The server returns structured JSON containing the solution:

```json
{
  "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`](https://github.com/cr2007/mcp-wordle-python/blob/main/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`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py) or adjust dependencies in [`pyproject.toml`](https://github.com/cr2007/mcp-wordle-python/blob/main/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.