Skip to main content
Glama
jalali-calendar-mcp

jalali-calendar-mcp

jalali-calendar-mcp

An MCP server and Python library for the Iranian (Jalali, Solar Hijri) calendar: today in Iran, date conversion, months, official holidays and workdays.

Fully offline. It calls no web service and needs no account or token. Every date is calculated inside the package.

Tools

Tool

What it returns

today()

Today in Iran (Asia/Tehran), Jalali and Gregorian, weekday, and whether it is a day off

convert_date(value)

The same for any date, Jalali ↔ Gregorian

get_month(year, month)

Every day of a Jalali month, with Fridays and holidays

get_holidays(year)

Iran's official holidays in a Jalali year

is_holiday(value)

Whether a day is a Friday or an official holiday, and which

count_workdays(start, end)

Days in a range that are neither Fridays nor official holidays

Dates are accepted as Gregorian YYYY-MM-DD or Jalali YYYY/MM/DD, with Persian or English digits; any year below 1700 is read as Jalali. Holidays are available for Jalali years 1304–1455.

Related MCP server: calso

How sure is a holiday?

Every holiday carries a status:

Status

Meaning

official

A fixed solar holiday set by law: Nowruz (1–4 Farvardin), 12 and 13 Farvardin, 14 and 15 Khordad, 22 Bahman, 29 Esfand

listed

A lunar (Hijri) holiday from the package's list for that year (currently 1405, taken from persian-calendar.ir and not yet checked against the official calendar)

estimated

A lunar holiday calculated with the Umm al-Qura calendar. Iran starts each lunar month from its own moon sighting, so it may be one day off. Check the official calendar before relying on it

Lunar holidays move about 11 days earlier each year. A day can hold two holidays; in 1405, for example, Nowruz and Eid al-Fitr share 1 Farvardin. Fridays are the weekly day off and are reported as is_friday, not as holidays. count_workdays counts Thursdays as workdays. It is not a legal deadline calculator: legal periods have their own rules.

Setup

For Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "jalali-calendar": {
      "command": "uvx",
      "args": ["jalali-calendar-mcp"]
    }
  }
}

Or install it with pip install jalali-calendar-mcp and use "command": "jalali-calendar-mcp".

As a library

from jalali_calendar_mcp import holidays, holidays_on, jalali, parse_date

parse_date("۱۴۰۵/۰۱/۰۱")  # date(2026, 3, 21)
jalali(parse_date("2026-11-22"))  # "1405/09/01"
[h.name for h in holidays_on(parse_date("1405/04/04"))]  # ["عاشورای حسینی"]
len(holidays(1405))  # 29

Adding a year's lunar holidays

Add src/jalali_calendar_mcp/data/<year>.json, following 1405.json (with a source), with the lunar holidays from the official calendar of the University of Tehran Geophysics Institute. Set checked_against_official to true once someone has compared it with that calendar.

Development

uv sync
uv run ruff check . && uv run ruff format --check .
uv run pytest

فارسی

سرور MCP و کتابخانهٔ پایتون برای تقویم رسمی ایران (هجری شمسی): امروز به وقت ایران، تبدیل تاریخ شمسی و میلادی، روزهای هر ماه، تعطیلات رسمی و شمارش روزهای کاری.

کاملاً آفلاین: به هیچ سرویس اینترنتی وصل نمی‌شود و حساب کاربری یا توکن لازم ندارد.

ابزارها

ابزار

کاربرد

today

امروز به وقت ایران، شمسی و میلادی، و اینکه تعطیل است یا نه

convert_date

تبدیل تاریخ شمسی و میلادی به یکدیگر

get_month

همهٔ روزهای یک ماه شمسی با جمعه‌ها و تعطیلات

get_holidays

تعطیلات رسمی یک سال شمسی

is_holiday

آیا روزی جمعه یا تعطیل رسمی است

count_workdays

شمار روزهای کاری یک بازه، بدون جمعه‌ها و تعطیلات رسمی

میزان اطمینان تعطیلات

  • official: تعطیلات خورشیدی ثابت که قانون تعیین کرده است، مانند نوروز و ۲۲ بهمن.

  • listed: تعطیلات قمری از فهرست همان سال در این بسته (فعلاً ۱۴۰۵).

  • estimated: تعطیلات قمری محاسبه‌شده. چون آغاز ماه قمری در ایران با رؤیت هلال تعیین می‌شود، ممکن است یک روز با تقویم رسمی فرق داشته باشد. پیش از استفاده برای کار مهم، تقویم رسمی را ببینید.

جمعه‌ها تعطیل هفتگی‌اند و جدا از تعطیلات رسمی نشان داده می‌شوند. شمارش روزهای کاری جایگزین محاسبهٔ مهلت‌های قانونی نیست.

License

MIT

Available Tools

6 tools
convert_dateConvert a date (Jalali / Gregorian)A
Read-onlyIdempotent

Convert a date between the Jalali (Persian) and Gregorian calendars.

Args: value: Gregorian YYYY-MM-DD or Jalali YYYY/MM/DD (Persian digits are fine; any year below 1700 is Jalali).

Inputs: value (required). Returns: One day in both calendars, with whether it is a day off in Iran.

count_workdaysCount workdaysA
Read-onlyIdempotent

Count the days from start to end (both included) that are not Fridays or official holidays. Thursdays count as workdays. Not a legal deadline calculator: legal periods have their own rules.

Args: start: First day, Gregorian YYYY-MM-DD or Jalali YYYY/MM/DD. end: Last day, same formats (at most ten years after start).

Inputs: end (required), start (required). Returns: end, days, start, days_off, +4 more

get_holidaysOfficial holidays of a yearA
Read-onlyIdempotent

Iran's official holidays in a Jalali year, in date order. Fridays are not listed.

Args: year: Jalali year, e.g. 1405.

Inputs: year (required). Returns: year, holidays, lunar_status

get_monthA Jalali monthB
Read-onlyIdempotent

Every day of a Jalali month with its Gregorian date, weekday, Fridays and holidays.

Args: year: Jalali year, e.g. 1405. month: 1 (Farvardin) to 12 (Esfand).

Inputs: year (required), month (required). Returns: days, year, month, month_name, +1 more

is_holidayIs it a day off?A
Read-onlyIdempotent

Whether a day is a Friday or an official holiday in Iran, and which.

Args: value: Gregorian YYYY-MM-DD or Jalali YYYY/MM/DD.

Inputs: value (required). Returns: One day in both calendars, with whether it is a day off in Iran.

todayToday in IranA
Read-onlyIdempotent

Today's date in Iran (Asia/Tehran), Jalali and Gregorian, and whether it is a day off.

Inputs: no named parameters. Returns: One day in both calendars, with whether it is a day off in Iran.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool targets a distinct query shape: conversion, today's snapshot, month listing, year holiday listing, single-day holiday check, and range workday counting. The mild overlaps (get_holidays vs is_holiday, get_month's holiday annotation vs get_holidays) are resolved by clear differences in granularity (year list vs single day vs full month grid).

    Naming Consistency4/5

    Five of six tools follow a predictable verb_noun or verb_object pattern (convert_date, get_month, get_holidays, count_workdays, is_holiday). The lone 'today' noun-only name is an understandable exception for a snapshot tool but is a minor deviation.

    Tool Count5/5

    Six tools is well within the sweet spot, and each one maps to a distinct, non-trivial calendar operation. Nothing feels redundant or padded.

    Completeness4/5

    Coverage spans conversion, current date, month view, holidays, holiday checking, and workday ranges — the core needs of a Jalali calendar server. Minor gaps remain, such as date arithmetic (add/subtract days), week views, or finding the next holiday/working day, but agents can work around these.

    Maintenance

    ActivityNo data
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Calso, a local Persian calendar and task manager. It provides 17 tools enabling AI to create tasks, read schedules, and plan days with Solar Hijri dates.
      3 npm
      4
      ISC
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to work with Iran-specific data and Persian/RTL frontends fully offline, covering Jalali date conversion, national ID, card, Sheba and mobile validation, Persian text and number formatting, bank and operator lookup, VAT and price handling, plus RTL auditing and CSS/Tailwind conversion. All tools run locally with no API keys.
      56
      54 npm
      5
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to query Iran's official calendar from Time.ir, convert dates across Jalali, Gregorian, and Hijri calendars, check holidays and occasions, and retrieve prayer times for Iranian cities.
      13
      82 PyPI
      MIT