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

Metadata

Release files for jalali-calendar-mcp 0.2.1

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.1
File Size Uploaded Provenance Actions
jalali_calendar_mcp-0.2.1.tar.gz 12.4 kB Without provenance Details for jalali_calendar_mcp-0.2.1.tar.gz

Built distribution (wheel)

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

Total release size: 25.1 kB

Release files / jalali_calendar_mcp-0.2.1.tar.gz

Download URL jalali_calendar_mcp-0.2.1.tar.gz
Size 12.4 kB
Tags Source
SHA-256 checksum
How to use checksums
f6af3569b0ef0735d32df96d58e3f3fa72e9a7b8e37fb6c64a397bbd9262dfe5
BLAKE2b-256 checksum
How to use checksums
a401bbc89480e66a2472e39e59132e3f8f0697f4512894ecef2f79c0e549d695
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.1-py3-none-any.whl

Download URL jalali_calendar_mcp-0.2.1-py3-none-any.whl
Size 12.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b72ff1fb0c2f2b17dfe91cc75abf7a2726a9592f6470fed4370c4d4032efbdf0
BLAKE2b-256 checksum
How to use checksums
39fbae4e15e25a26cf9869433864dc767ee7e8655f1f1675d8869cba9909950d
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.1

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