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

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, the server initializes a FastMCP instance:

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	Contains the FastMCP setup, tool decorator, and get_wordle_data implementation (lines 1‑68).
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:

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, the function interpolates the target_date parameter directly into the New York Times Wordle API endpoint:

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:

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)

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

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

Requesting a Future Date (Within 23-Day Window)

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

Handling API Error Responses

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:

{
  "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 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. 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.

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