--- name: persian-calendar description: "Convert explicit Persian and Gregorian civil dates, retrieve today in an IANA timezone, and inspect Persian month boundaries through public read-only tools." --- # Persian Calendar — Developer and Agent Guide Website: https://persiancalendar.online Human-readable guide: https://persiancalendar.online/developers OpenAPI: https://persiancalendar.online/openapi.json MCP endpoint: https://persiancalendar.online/mcp ## When to use this service Use Persian Calendar for explicit Gregorian–Persian civil-date conversion, today’s Persian date in a named timezone, and exact Persian month lengths and boundaries. The endpoints are public, read-only and do not require an account or API key. Ask which input calendar and date format the user means. An ambiguous date such as 03/04/2026 is not an accepted API format. Use ASCII YYYY-MM-DD; the website’s interactive converter also accepts Persian and Arabic numerals. ## Method and supported input The website, API and agent tools use the same jalaali-js calculation engine. Public input years are 1800–2200 for Gregorian dates and 1280–1600 for Persian dates. Limits apply to the input calendar; the converted output can fall outside the other input range. The interactive website retains its broader historical range. Impossible dates return HTTP 400 with an error string. For example, 2026-02-31 and Persian 1405-12-30 are rejected. Never silently normalize invalid input. Date-only conversion does not shift a date between timezones. These are civil-calendar calculations. They do not calculate the astronomical instant of the equinox or solstice. The celebration guides record cultural calendar conventions and are not a statutory public-holiday service. ## Today, timezones and freshness Supply timeZone as a valid IANA name, such as Asia/Tehran, Europe/London or UTC. The response reports the resolved timeZone and the calculation timestamp. An invalid timezone returns HTTP 400. Without this parameter, /api/today preserves its existing server-timezone behavior; it does not infer the visitor’s location. Live API and MCP responses use Cache-Control: no-store. Recalculate “today” when its timezone crosses midnight. The isHoliday field is retained for compatibility: it marks a Friday or a date in the site’s cultural collection, not verified legal holiday status. ## MCP and browser tools Connect a compatible remote MCP client to https://persiancalendar.online/mcp using Streamable HTTP. The stateless endpoint supports the 2026-07-28 protocol and legacy stateless clients through the official MCP TypeScript SDK. Authentication is not required. Available tools: convert_date, get_today, get_persian_month. The same three read-only tools are registered through WebMCP when the browser exposes a supported modelContext API. Other browsers continue using the ordinary website. WebMCP availability depends on the browser and agent; remote MCP does not require an open website tab. Tool results include a source URL tied to the requested date, year or timezone. Cite that URL with the returned context. Documentation describes supported operations; publishing it does not guarantee that an assistant will discover, recommend or cite the website. ## Access and response handling Server-to-server callers can request the public HTTPS endpoints directly. Browser CORS permissions retain the site’s existing origin restrictions. There are no credentialed operations. Handle HTTP 400 errors instead of presenting their contents as a successful conversion. The month endpoint takes a Persian year and a month number from 1 to 12. It returns the exact Gregorian start/end dates, actual day count, leap-year flag and a firstWeekdayIndex with Saturday = 0 through Friday = 6. ## Request examples ### Gregorian to Persian GET https://persiancalendar.online/api/convert?from=gregorian&date=2027-03-21 Expected: 1 Farvardin 1406. ### Persian to Gregorian GET https://persiancalendar.online/api/convert?from=persian&date=1406-01-01 Expected: 2027-03-21. ### Today in Tehran GET https://persiancalendar.online/api/today?timeZone=Asia%2FTehran Expected: A fresh date and timestamp in Asia/Tehran. ### Esfand in a leap year GET https://persiancalendar.online/api/month?year=1403&month=12 Expected: 30 days; 2025-02-19 through 2025-03-20. ## Reference pages - [Calendar method and limitations](https://persiancalendar.online/about#calendar-method) - [Celebrations](https://persiancalendar.online/celebrations) - [Month guides](https://persiancalendar.online/months) - [Permanent poetry archive](https://persiancalendar.online/verse/theme)