jalali-calendar-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jalali-calendar-mcp What's today's date in Iran, and is it a holiday?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 in Iran (Asia/Tehran), Jalali and Gregorian, weekday, and whether it is a day off |
| The same for any date, Jalali ↔ Gregorian |
| Every day of a Jalali month, with Fridays and holidays |
| Iran's official holidays in a Jalali year |
| Whether a day is a Friday or an official holiday, and which |
| 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 |
| A fixed solar holiday set by law: Nowruz (1–4 Farvardin), 12 and 13 Farvardin, 14 and 15 Khordad, 22 Bahman, 29 Esfand |
| 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) |
| 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)) # 29Adding 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 و کتابخانهٔ پایتون برای تقویم رسمی ایران (هجری شمسی): امروز به وقت ایران، تبدیل تاریخ شمسی و میلادی، روزهای هر ماه، تعطیلات رسمی و شمارش روزهای کاری.
کاملاً آفلاین: به هیچ سرویس اینترنتی وصل نمیشود و حساب کاربری یا توکن لازم ندارد.
ابزارها
ابزار | کاربرد |
| امروز به وقت ایران، شمسی و میلادی، و اینکه تعطیل است یا نه |
| تبدیل تاریخ شمسی و میلادی به یکدیگر |
| همهٔ روزهای یک ماه شمسی با جمعهها و تعطیلات |
| تعطیلات رسمی یک سال شمسی |
| آیا روزی جمعه یا تعطیل رسمی است |
| شمار روزهای کاری یک بازه، بدون جمعهها و تعطیلات رسمی |
میزان اطمینان تعطیلات
official: تعطیلات خورشیدی ثابت که قانون تعیین کرده است، مانند نوروز و ۲۲ بهمن.listed: تعطیلات قمری از فهرست همان سال در این بسته (فعلاً ۱۴۰۵).estimated: تعطیلات قمری محاسبهشده. چون آغاز ماه قمری در ایران با رؤیت هلال تعیین میشود، ممکن است یک روز با تقویم رسمی فرق داشته باشد. پیش از استفاده برای کار مهم، تقویم رسمی را ببینید.
جمعهها تعطیل هفتگیاند و جدا از تعطیلات رسمی نشان داده میشوند. شمارش روزهای کاری جایگزین محاسبهٔ مهلتهای قانونی نیست.
License
MIT
Available Tools
6 toolsconvert_dateConvert a date (Jalali / Gregorian)ARead-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 workdaysARead-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 yearARead-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 monthBRead-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?ARead-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 IranARead-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
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.
Maintenance
Related MCP Connectors
Persian and Iranian utilities for agents: Jalali dates, national ID, IBAN, holidays. Paid via x402.
Count days between dates, add or subtract dates, and look up public holidays by country.
Business-day, SLA, cron and recurrence calculations — offline, holiday-aware, no network.
Count workdays, office days and PTO days, or list bank holidays and school breaks.
Related MCP Servers
- AlicenseAqualityCmaintenanceProvides Japanese national holidays, wareki (era) conversion, and date information. Works fully offline with no API keys required.4MIT
- AlicenseNot gradedqualityDmaintenanceMCP 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 npm4ISC
- AlicenseBqualityBmaintenanceEnables 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.5654 npm5MIT
- AlicenseAqualityBmaintenanceEnables 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.1382 PyPIMIT