Skip to main content
Glama

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.

PyPI Python CI License: PolyForm Noncommercial

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-mcp or claude 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-DD strings 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

ti_today

Get today's date in the Jalali, Gregorian and Hijri calendars with the Tehran time, weekday, zodiac sign and today's events

ti_convert_date

Convert a date between the Jalali, Gregorian and Hijri calendars with time.ir's own converter

ti_month

Show one Jalali month: Gregorian and Hijri spans, weekday of day 1, holidays, Fridays and every event

ti_events

List the occasions and official holidays of one day, with a short description when time.ir has one

ti_holidays

List all official holidays of a Jalali year with Gregorian and Hijri dates

ti_upcoming_holidays

List the next official holidays in Iran with days until each

ti_prayer_times

Get today's prayer times (fajr, sunrise, noon, sunset, maghrib, Islamic midnight, day length) for an Iranian city

ti_cities

List Iran's provinces, or the cities of one province, with the ids the prayer tool takes

ti_on_this_day

List today's historical events, births and deaths of notable people from time.ir's today page

ti_search_events

Search all occasions of a Jalali year by keyword, holiday flag or calendar

ti_date_difference

Count days between two dates and give Jalali years, months, days (age calculator)

ti_long_weekends

Find runs of consecutive days off (holidays plus Fridays) in a Jalali year

ti_qibla

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

Claude 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 build

Disclaimer

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 tools
ti_citiesCitiesA
Read-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 dateA
Read-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 differenceA
Read-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 dayA
Read-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 yearA
Read-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 weekendsA
Read-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 calendarA
Read-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 historyA
Read-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 timesA
Read-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 directionA
Read-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 occasionsA
Read-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_todayTodayA
Read-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 holidaysA
Read-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

    A4.1/5.0

    Scored across 13 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides 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.
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides AI agents with accurate current time and date, including the Jalali (Persian) calendar, timezone-aware with automatic DST handling, via an MCP server.
      2
      1
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      56
      54 npm
      5
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      11
      PolyForm Noncommercial 1.0.0