time-ir-mcp
A read-only MCP server for Iran's time.ir calendar, date conversion, holidays/occasions, and prayer/Qibla info.
Get today’s date/time in Jalali, Gregorian, and Hijri calendars with weekday, zodiac, and events.
Convert dates between Jalali, Gregorian, and Hijri calendars.
Show a Jalali month’s spans, weekdays, holidays, and events.
List a day’s occasions/holidays, or all official holidays in a Jalali year.
Find upcoming holidays with days-until counts.
List provinces/cities and get prayer times for Iranian cities.
Get Qibla bearing and distance to Mecca for a city.
Show historical events, births, and deaths for today.
Search occasions by keyword, calendar, or holiday-only flag.
Count days between dates and give Jalali years/months/days.
Find long weekends/holiday runs in a Jalali year.
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., "@time-ir-mcp What's today's date in the Jalali calendar?"
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.
time-ir-mcp: Time.ir Iranian calendar MCP server for AI agents
time-ir-mcp is an unofficial, read-only MCP server that gives AI agents the Iranian calendar of Time.ir (تایم، تقویم و ساعت ایران). Its 13 tools give today's date in the Jalali, Gregorian and Hijri calendars, convert dates, show a month with its events, list the occasions and official holidays of a day or a year, find the next holidays and return today's prayer times (اوقات شرعی) for Iranian cities, search occasions, count date differences and find long weekends. No API key or account is needed. It works in Claude, Cursor, Copilot and any other MCP client.
For AI agents · Quick start · Tools · Good to know · فارسی
For AI agents
What: unofficial MCP server (model context protocol) for time.ir: the date and time in Iran in three calendars, date conversion, official holidays, monthly and daily occasions (مناسبتها) and prayer times for Iranian cities.
Install:
uvx time-ir-mcporclaude mcp add time-ir -- uvx time-ir-mcp. Transport: stdio. Needs uv (Python 3.10+).Auth: none. Optional
TIME_IR_MCP_PROXY(HTTP proxy URL, or a comma-separated list); system proxy settings are ignored.Access: read-only. Nothing is written anywhere, so no confirmation is needed before calling any tool.
Tools: 13, all prefixed
ti_. Typical sequences:ti_today;ti_events(is it a holiday?);ti_upcoming_holidays;ti_cities->ti_prayer_times.Use when: the user asks what the date is in Iran, to convert between Jalali (شمسی), Gregorian (میلادی) and Hijri (قمری) dates, whether a day is an official holiday, what occasions a day has, when the next holiday is, or the azan times of an Iranian city.
Do not use when: the user wants other countries' holidays or times (Time.ir covers Iran's official calendar only).
Output: compact JSON. Dates are
YYYY-MM-DDstrings in the Jalali, Gregorian and Hijri calendars; times are Iran local time (24 h). Titles and descriptions are Persian, as Time.ir has them.
Related MCP server: local-time-mcp
Tools
Tool | What it does |
| Get today's date in the Jalali, Gregorian and Hijri calendars with the Tehran time, weekday, zodiac sign and today's events |
| Convert a date between the Jalali, Gregorian and Hijri calendars with time.ir's own converter |
| Show one Jalali month: Gregorian and Hijri spans, weekday of day 1, holidays, Fridays and every event |
| List the occasions and official holidays of one day, with a short description when time.ir has one |
| List all official holidays of a Jalali year with Gregorian and Hijri dates |
| List the next official holidays in Iran with days until each |
| Get today's prayer times (fajr, sunrise, noon, sunset, maghrib, Islamic midnight, day length) for an Iranian city |
| List Iran's provinces, or the cities of one province, with the ids the prayer tool takes |
| List today's historical events, births and deaths of notable people from time.ir's today page |
| Search all occasions of a Jalali year by keyword, holiday flag or calendar |
| Count days between two dates and give Jalali years, months, days (age calculator) |
| Find runs of consecutive days off (holidays plus Fridays) in a Jalali year |
| Get the qibla bearing and distance to Mecca for an Iranian city (computed from the site's coordinates) |
All 13 tools are annotated readOnlyHint: true.
Quick start
You need uv. No API key or account.
claude mcp add time-ir -- uvx time-ir-mcpClaude Desktop, Cursor, Windsurf and Gemini CLI take the same stdio entry:
{
"mcpServers": {
"time-ir": { "command": "uvx", "args": ["time-ir-mcp"] }
}
}Example prompts: "What is today's Jalali date?", "Is 25 December a holiday in Iran?", "When is the next official holiday?", "Convert 1405-01-01 to Gregorian and Hijri.", "Azan times in Mashhad today." «تاریخ امروز به شمسی چیست؟»، «اذان ظهر شیراز چه ساعتی است؟»، «تعطیلات رسمی بهمن ۱۴۰۵ کداماند؟»
Good to know
Iran's official calendar only. Holidays are Iran's; the Hijri date is Iran's (it can differ by a day from Saudi Arabia's). No world clock.
Friday is the weekend and is not reported as a holiday on its own; a Friday that is also an occasion holiday is.
Prayer times are for the Jalali date given (other calendars are converted first) in Iran local time. Cities that are not provincial capitals need
province.Persian data. Titles and descriptions are Persian. Event descriptions are HTML on the site; the tool returns plain text, cut at 900 characters.
Fragile by nature. The site has no public API; if it changes its pages, a tool can fail until the server is updated.
فارسی
time-ir-mcp یک سرور MCP غیررسمی و فقطخواندنی برای تایم (تقویم و ساعت ایران) است: تاریخ امروز به شمسی، میلادی و قمری، تبدیل تاریخ، مناسبتها و تعطیلات رسمی، و اوقات شرعی شهرهای ایران.
نصب (با uv): claude mcp add time-ir -- uvx time-ir-mcp. کلید API یا حساب لازم نیست. اگر شبکهٔ شما درخواستها را مسدود کرد، متغیر TIME_IR_MCP_PROXY را روی یک پراکسی HTTP بگذارید.
Development
uv sync
uv run ruff check . && uv run ruff format --check .
uv run python -m pytest -q # offline tests on recorded time.ir answers
uv run python -m pytest -m live -q # calls the real time.ir site
uv buildDisclaimer
Unofficial and not affiliated with or endorsed by Time.ir or Radcom. It is read-only and uses the public pages of www.time.ir, which can change without notice. For religious or legal purposes check the official sources.
Author
Built and maintained by Sepehr Radmard (سپهر رادمرد). Connect on LinkedIn or follow @sepehr071 on GitHub for more MCP servers for Iranian websites, all listed in iran-mcp.
مجوز استفاده (License)
استفادهٔ شخصی و غیرتجاری رایگان است. استفاده در شرکت، محصول پولی یا پروژهٔ مشتری به مجوز تجاری نیاز دارد؛ از راه لینکدین یا گیت‌هاب با سپهر رادمرد تماس بگیرید. متن کامل: PolyForm Noncommercial 1.0.0. نسخه‌های پیش از 0.2.1 با مجوز MIT منتشر شده‌اند و همان مجوز را دارند.
Free for personal and non-commercial use under the PolyForm Noncommercial License 1.0.0. Using it in a company, a paid product or a client project needs a commercial license: contact Sepehr Radmard on LinkedIn or GitHub. Versions before 0.2.1 were released under MIT and stay under it.
Available Tools
13 toolsti_citiesCitiesARead-onlyIdempotent
List Iran's provinces, or the cities of one province, with the ids ti_prayer_times takes.
No arguments: 31 provinces with capital city ids. With province: its cities with lat/lng.
Inputs: query, province.
ti_convert_dateConvert dateARead-onlyIdempotent
Convert a date between the Jalali (Solar Hijri), Gregorian and Hijri (lunar) calendars, using time.ir's own converter.
Hijri is Iran's official date (may differ by a day from Saudi Arabia's).
Inputs: date (required), calendar.
ti_date_differenceDate differenceARead-onlyIdempotent
Count the days between two dates and give the span as Jalali years, months and days (age calculator).
Omit to_date for today. Both dates use calendar. If to_date is earlier, direction is "before".
Inputs: from_date (required), to_date, calendar.
ti_eventsEvents of a dayARead-onlyIdempotent
List the occasions (Persian: monasebat) and official holidays of one day, with a short description when time.ir has one.
Use for "is 2026-12-25 a holiday in Iran". Each event has calendar (where the occasion belongs) and holiday.
Friday alone is not a holiday.
Inputs: date, calendar.
ti_holidaysHolidays of a yearARead-onlyIdempotent
List all official holidays (تعطیلات رسمی) of a Jalali year with Gregorian and Hijri dates and weekdays.
Fridays are listed only when also an occasion holiday. For "the next holiday" use ti_upcoming_holidays.
Inputs: year.
ti_long_weekendsLong weekendsARead-onlyIdempotent
Find runs of consecutive days off in a Jalali year: official holidays joined with Fridays (optionally Thursdays).
Use for "long weekends in 1405". Bridge days are not counted; runs are cut at the year boundary.
Inputs: year, min_days, thursday_off.
ti_monthMonth calendarARead-onlyIdempotent
Show one Jalali month: its Gregorian and Hijri month spans, weekday of day 1, holidays and every event of the month.
Use for "holidays this month". For one day with descriptions use ti_events.
Inputs: year, month.
ti_on_this_dayOn this day in historyARead-onlyIdempotent
List today's historical events, birthdays and deaths of notable people, as Time.ir's "today" page shows them.
Today only. Each item's date is as Time.ir prints it (Gregorian with year for history, Jalali day for national occasions).
Inputs: kind.
ti_prayer_timesPrayer timesARead-onlyIdempotent
Get the Islamic prayer times (اوقات شرعی) for an Iranian city and day: fajr, sunrise, noon, sunset, maghrib and Islamic midnight.
Iran local time, 24 h. Today only: another date returns an error. Non-capital cities need province.
Inputs: city (required), date, calendar, province.
ti_qiblaQibla directionARead-onlyIdempotent
Get the qibla direction (bearing to the Kaaba in Mecca, degrees clockwise from true north) and distance for an Iranian city.
Computed from the city's coordinates (great circle), not by Time.ir. Bearing is from true north.
Inputs: city (required), province.
ti_search_eventsSearch occasionsARead-onlyIdempotent
Search all occasions (monasebat) of a Jalali year by keyword and return each match with its dates.
Use for "when is Teacher's Day". Title matches first, then description matches, each in date order.
Inputs: query (required), year, limit, calendar, +1 more.
ti_todayTodayARead-onlyIdempotent
Get today's date in the Jalali, Gregorian and Hijri calendars with the Tehran time, weekday, zodiac sign and today's events.
Use first for "today", "now" or the date/time in Iran.
Inputs: no named parameters.
ti_upcoming_holidaysUpcoming holidaysARead-onlyIdempotent
List the next official holidays in Iran starting today (or from_date), with days until each.
Use for "when is the next holiday". Fridays alone are not listed.
Inputs: count, calendar, from_date.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools have clearly distinct purposes, and descriptions explicitly steer common intents such as 'next holiday' and 'holidays this month'. There is still some conceptual overlap among ti_today, ti_events, ti_month, ti_holidays, ti_upcoming_holidays, and ti_long_weekends because they all surface holidays or events in different scopes, so an agent may occasionally need to compare descriptions.
All tools use a consistent ti_ prefix and snake_case throughout. The names mix noun-style query names (ti_today, ti_month) with verb_noun names (ti_convert_date, ti_search_events), but the pattern remains highly predictable.
The 13 tools are well-scoped for an Iranian calendar/time/event/prayer server. Each tool covers a distinct query type, and the count sits comfortably in the appropriate range without obvious bloat or missing core operations.
The surface broadly covers date conversion, today/month/year views, events, holidays, upcoming holidays, long weekends, prayer times, qibla, cities, historical events, search, and date differences. The main notable gap is that prayer times only work for today, so an agent cannot retrieve prayer times for another date.
Maintenance
Related MCP Connectors
Persian and Iranian utilities for agents: Jalali dates, national ID, IBAN, holidays. Paid via x402.
Time and date math for AI agents: Unix timestamp conversion, DST-correct time zone conversion, durations, epoch arithmetic, cron schedules, and holiday countdowns. Eight tools, no key.
Deterministic time tools for AI agents: timezone conversion, business-day math, cron interpretation.
Current time, timezone conversion & date math for AI agents. On Cloudflare Workers.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides AI assistants with rich temporal intelligence including timezone conversions, 9 cultural calendars (Hebrew, Islamic, Chinese, etc.), astronomical events, Islamic prayer times, and context-aware activity appropriateness recommendations.3MIT
- AlicenseAqualityDmaintenanceProvides AI agents with accurate current time and date, including the Jalali (Persian) calendar, timezone-aware with automatic DST handling, via an MCP server.211MIT
- 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 search Iranian places, read place details, reviews, photos and menus, find nearby places, reverse geocode coordinates, check air quality, and get car, motorcycle, bicycle, walking or bus/metro directions, travel times and Tehran traffic-zone status without an API key.11PolyForm Noncommercial 1.0.0