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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.