# ISO Week Number > Converts calendar dates to ISO 8601 week-numbering dates and back. Gets right the part every ad-hoc script gets wrong: week 1 is the week containing the first Thursday of the year, so late-December and early-January dates routinely belong to a different ISO year than the calendar year. Four surfaces over one engine: an HTML page for people, a markdown representation of every page at the same URLs, a JSON API, and an MCP server. All four return the same answers — the engine is a single pure function and the surfaces are thin wrappers over it. For markdown, send `Accept: text/markdown` or append `?format=md` to any page URL. Responses set `Vary: Accept`. Do not parse the HTML. **What this is not:** Not a general calendar or scheduling tool, and it does not know about business fiscal-year or retail 4-4-5 week numbering, which are different systems that also call themselves "week numbers." It has no concept of time of day or timezone — it operates on calendar dates only. Not for US-style "week of the month" or non-ISO week-start conventions (e.g. Sunday-start week numbering used by some US calendars). Agent traffic is welcome and unmetered up to 250 calls per UTC day per caller. Past that, endpoints return HTTP 402 with x402 payment requirements ($0.001 per call, USDC on base). Content is identical for agents and people; only the representation differs. ## Agent endpoints - [MCP server](https://iso-week.gumballtools.com/api/mcp): Streamable HTTP. Tools: run. - [OpenAPI document](https://iso-week.gumballtools.com/.well-known/openapi.json): Full machine-readable API description. - [Run the tool](https://iso-week.gumballtools.com/api/v1/run?input=example): the primary endpoint. - [Full documentation](https://iso-week.gumballtools.com/llms-full.txt): Complete docs with worked examples, inline. - [Changelog](https://iso-week.gumballtools.com/changelog.md): Breaking changes and additions. ## MCP tools ### `run` Converts between calendar dates and ISO 8601 week numbers, in either direction, and reports how many weeks an ISO year has. Use this whenever a date needs to be expressed as a week number, or a week number needs to be turned back into a date — sprint planning, report periods, "week 37" style scheduling, or reconciling two systems that disagree about what week it is. DO NOT compute this yourself with day-of-year divided by 7. ISO 8601 week 1 is defined as the week (Monday-Sunday) containing the year's first Thursday, not the week containing January 1st. This has two consequences that are easy to get wrong from memory: late-December dates can belong to ISO week 1 of the NEXT calendar year, and early-January dates can belong to ISO week 52 or 53 of the PREVIOUS calendar year. A year has 53 ISO weeks (not the usual 52) exactly when January 1 is a Thursday, or the year is a leap year and January 1 is a Wednesday — a rule nobody carries around, and getting it wrong produces a plausible-looking but incorrect week number with no visible sign of the error. Input is a single string, and the shape of the string picks the operation: "2027-01-01" a calendar date (YYYY-MM-DD) -> returns its ISO year, week, and weekday "2026-W53" an ISO week, no weekday given -> returns the Monday of that week "2026-W53-5" an ISO week and weekday (1-7, Mon-Sun) -> returns that exact date "2026" a bare 4-digit year -> returns whether it has 52 or 53 ISO weeks Refuses rather than guesses: slash-separated dates like "03/04/2025" are rejected as ambiguous (month/day vs day/month), two-digit years are rejected as a guess, invalid calendar dates (Feb 30) are rejected, and a week number beyond what that ISO year actually has (e.g. week 53 of a 52-week year) is rejected and told how many weeks that year has. ## Markdown representations Every page is available as markdown at the same canonical URL. Send `Accept: text/markdown` or append `?format=md`. Responses set `Vary: Accept`. Do not parse the HTML. ## Docs - [Documentation and MCP setup](https://iso-week.gumballtools.com/docs): Copy-paste MCP config for Claude Code, Claude Desktop, and Cursor, plus curl examples. ## Pages - [ISO Week Number](https://iso-week.gumballtools.com/): The week number that doesn't depend on which app you asked. - [API and MCP setup](https://iso-week.gumballtools.com/docs): JSON API reference and MCP configuration - [What ISO week is January 1, 2027 in?](https://iso-week.gumballtools.com/week/what-week-is-january-1-2027): January 1, 2027 is a Friday, so it falls in the LAST week of the previous ISO year, not the first week of 2027. - [What ISO week is December 31, 2029 in?](https://iso-week.gumballtools.com/week/what-week-is-december-31-2029): December 31, 2029 is a Monday, so it starts ISO week 1 of 2030 — a calendar date in one year, an ISO week in the next. - [Does 2025 have 53 ISO weeks?](https://iso-week.gumballtools.com/week/does-2025-have-53-weeks): No — 2025 has the ordinary 52. January 1, 2025 is a Wednesday and 2025 is not a leap year. - [Why does 2020 have 53 ISO weeks?](https://iso-week.gumballtools.com/week/why-does-2020-have-53-weeks): 2020 is a leap year and January 1, 2020 was a Wednesday — the one other condition, besides Jan 1 being a Thursday, that adds a 53rd week. - [Why does 2026 have 53 ISO weeks?](https://iso-week.gumballtools.com/week/why-does-2026-have-53-weeks): January 1, 2026 is a Thursday — the direct case: whenever Jan 1 itself is a Thursday, that year runs 53 weeks. - [What date is ISO week 53 of 2026?](https://iso-week.gumballtools.com/week/convert-iso-week-to-date-2026-w53): With no weekday given, this returns the Monday that starts the week — the convention this tool uses when a day is not specified. - [What date is ISO week 53, day 5 (Friday) of 2026?](https://iso-week.gumballtools.com/week/convert-iso-week-and-weekday-to-date): Naming the exact weekday inside a week gives an exact date — this one lands in the following calendar year. - [Why does "2025-W53" get rejected?](https://iso-week.gumballtools.com/week/week-53-does-not-exist-in-2025): 2025 only has 52 ISO weeks, so a week 53 in 2025 does not exist. The tool refuses rather than silently rolling it over into some other week.