Skip to main content

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.

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)
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 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

Metadata

Release files for jalali-calendar-mcp 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jalali-calendar-mcp 0.2.0
File Size Uploaded Provenance Actions
jalali_calendar_mcp-0.2.0.tar.gz 12.3 kB Without provenance Details for jalali_calendar_mcp-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jalali-calendar-mcp 0.2.0
File Interpreter ABI Platform Actions
jalali_calendar_mcp-0.2.0-py3-none-any.whl Python 3 none any Details for jalali_calendar_mcp-0.2.0-py3-none-any.whl

Total release size: 24.9 kB

Release files / jalali_calendar_mcp-0.2.0.tar.gz

Download URL jalali_calendar_mcp-0.2.0.tar.gz
Size 12.3 kB
Tags Source
SHA-256 checksum
How to use checksums
282bdc27a6bbe2438779838671f0084376b432cb795d5961baa66fbd9bc46279
BLAKE2b-256 checksum
How to use checksums
b2a62bc0b6e4872c32e100d6e81bd0e038d54a544b62f6ed43f73784e768d739
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / jalali_calendar_mcp-0.2.0-py3-none-any.whl

Download URL jalali_calendar_mcp-0.2.0-py3-none-any.whl
Size 12.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6a4b1f5c005218ad4bf7ec3639f7a10fbac75967386abcf7b9b17f459c3d72a8
BLAKE2b-256 checksum
How to use checksums
67ea97b22a84d8585483f79aded8cd3aadf78dab95ced239c908fb195c57b7fa
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for jalali-calendar-mcp 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page