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

Tools

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." «تاریخ امروز به شمسی چیست؟»، «اذان ظهر شیراز چه ساعتی است؟»، «تعطیلات رسمی بهمن ۱۴۰۵ کدام‌اند؟»

How it works

time-ir-mcp runs locally and calls the same "server actions" the time.ir pages call (www.time.ir is a Next.js app; the site's server reads api.time.ir with its own key, which this server never sees). Requests go out through a Chrome-impersonating client, spaced at least one second apart, cached for 10 minutes (the current time is never cached), and only to www.time.ir. Action ids change when the site is redeployed; when the site rejects one, the server looks the new id up by function name in the site's scripts and retries once.

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.

فارسی

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

MIT