# Working with Date Parameters in MCP Server Tools: A Complete Guide to the Wordle MCP Implementation

> Master date parameters in MCP server tools. Learn how the get_wordle_data tool retrieves Wordle solutions using ISO-8601 date strings for historical and future data. Get today's Wordle easily.

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

---

**The Wordle MCP server exposes a `get_wordle_data` tool that accepts an ISO-8601 date string parameter to retrieve historical or future Wordle solutions, defaulting to today's date when no argument is provided.**

The `cr2007/mcp-wordle-python` repository demonstrates how to implement date-aware tools in MCP (Model Context Protocol) servers using FastMCP. This Python-based server exposes a single tool that interacts with the New York Times Wordle API, leveraging date parameters to fetch solutions for any valid date within the supported range.

## Understanding the MCP Tool Architecture

The Wordle MCP server uses the **FastMCP** framework to register and expose tools. The architecture centers on a single Python file that defines the server instance, decorates functions as tools, and handles HTTP communication with external APIs.

### The FastMCP Instance and Tool Registration

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:

```python
mcp = FastMCP("WordleMCP")

```

The `@mcp.tool` decorator (lines 30‑38) registers the `get_wordle_data` function as an MCP tool, providing the name, description, and parameter schema that clients like Claude Desktop use to discover capabilities.

### Source File Structure

| File | Purpose |
|------|---------|
| [`src/mcp_wordle/main.py`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py) | Contains the FastMCP setup, tool decorator, and `get_wordle_data` implementation (lines 1‑68). |
| [`pyproject.toml`](https://github.com/cr2007/mcp-wordle-python/blob/main/pyproject.toml) | Declares runtime dependencies (`fastmcp`, `requests`) and the console script entry point `mcp-wordle`. |

## How Date Parameters Work in MCP Tools

The `get_wordle_data` tool accepts a single date parameter that controls which Wordle solution to retrieve. Understanding how this parameter is defined, validated, and defaulted is essential for building similar date-aware MCP tools.

### Parameter Definition and Default Values

The `target_date` parameter is defined in the function signature on line 39 of [`src/mcp_wordle/main.py`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py):

```python
async def get_wordle_data(target_date: str = date.today().isoformat()) -> dict:

```

**Key characteristics:**
- **Type:** `str` – The parameter accepts ISO-8601 formatted strings (e.g., `"2025-06-27"`).
- **Default:** `date.today().isoformat()` – When callers omit the parameter, the function automatically uses today's date.
- **Format:** `YYYY-MM-DD` – Documented in the docstring (lines 49‑51).

### Supported Date Ranges and Validation

The Wordle API enforces temporal boundaries rather than the MCP server performing local validation. The supported range spans from **2021‑05‑19** (Wordle's launch) to **23 days in the future** from the request date (documented in lines 59‑61).

If a client supplies a date outside this window, the New York Times API returns an error JSON, which `get_wordle_data` passes directly back to the caller without transformation.

## Implementing Date-Based API Calls

The implementation demonstrates how to construct dynamic URLs from date parameters and handle external API responses within an MCP tool context.

### Building the API Endpoint URL

On line 64 of [`src/mcp_wordle/main.py`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py), the function interpolates the `target_date` parameter directly into the New York Times Wordle API endpoint:

```python
url = f"https://www.nytimes.com/svc/wordle/v2/{target_date}.json"

```

This approach treats the date string as a path segment, requiring the input to match the API's expected format exactly.

### Handling API Responses and Errors

The HTTP request executes on line 66 using the `requests` library:

```python
return requests.get(url, timeout=300).json()

```

**Error handling characteristics:**
- **Timeout:** Set to 300 seconds to accommodate potential API latency.
- **Response parsing:** The `.json()` method converts the HTTP response directly to a Python dictionary.
- **Error propagation:** API errors (such as invalid dates) return as JSON with error fields, which the function returns verbatim to the MCP client.

## Practical Code Examples

### Default Call (Today's Wordle)

```python
from mcp_wordle.main import get_wordle_data

# No argument → uses today's date

response = await get_wordle_data()
print(response)   # => {"solution": "CRANE", "id": 345, ...}

```

### Specifying a Historic Date

```python
await get_wordle_data(target_date="2022-01-15")

```

### Requesting a Future Date (Within 23-Day Window)

```python
await get_wordle_data(target_date="2025-07-15")

```

### Handling API Error Responses

```python
result = await get_wordle_data(target_date="2020-01-01")
if "status" in result and result["status"] != "ok":
    print("Error:", result["errors"])
else:
    print("Wordle solution:", result["solution"])

```

### Using the Tool from Claude Desktop

In Claude Desktop, invoke the tool by name:

```json
{
  "tool": "get_wordle_solution",
  "arguments": { "target_date": "2023-03-20" }
}

```

Claude will invoke the MCP server, receive the JSON response, and surface it in the chat.

## Summary

- **FastMCP decorator**: The `@mcp.tool` decorator in [`src/mcp_wordle/main.py`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py) registers Python functions as MCP tools, exposing them to clients like Claude Desktop.
- **ISO-8601 date handling**: The `target_date` parameter accepts `YYYY-MM-DD` strings, defaulting to `date.today().isoformat()` when omitted.
- **API integration**: The tool constructs dynamic URLs using f-strings and returns raw JSON responses from the New York Times Wordle API.
- **Validation strategy**: Date validation occurs at the API level (2021-05-19 to 23 days future), with errors passed directly back to the caller.

## Frequently Asked Questions

### What date format does the Wordle MCP tool require?

The `get_wordle_data` tool requires **ISO-8601 format** (`YYYY-MM-DD`) as documented in the docstring on lines 49‑51 of [`src/mcp_wordle/main.py`](https://github.com/cr2007/mcp-wordle-python/blob/main/src/mcp_wordle/main.py). The parameter type is `str`, and the default value uses `date.today().isoformat()` to generate the correct format automatically.

### How does the MCP server handle invalid dates?

The server does not perform local date validation. Instead, it passes the `target_date` directly to the New York Times Wordle API. If the date falls outside the supported range (prior to 2021‑05‑19 or more than 23 days in the future), the API returns an error JSON, which `get_wordle_data` returns verbatim to the client.

### Can I request future Wordle solutions through the MCP tool?

Yes, but only within a limited window. The Wordle API supports dates up to **23 days in the future** from the current date (documented in lines 59‑61). Attempting to retrieve solutions beyond this window results in an API error rather than the solution data.

### What happens if I don't provide a date parameter to get_wordle_data?

If you omit the `target_date` argument, the function uses the default value `date.today().isoformat()`, which returns today's date in `YYYY-MM-DD` format. This ensures the tool always has a valid date to query, defaulting to the current day's Wordle puzzle when no specific date is requested.