jalali-calendar-mcp
# jalali-calendar-mcp
An [MCP](https://modelcontextprotocol.io) 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`:
```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
```python
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
```sh
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
TDQS
Scored across 6 tools
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).
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.
Six tools is well within the sweet spot, and each one maps to a distinct, non-trivial calendar operation. Nothing feels redundant or padded.
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.