Skip to main content

jalali-calendar-mcp

An MCP server that lets an AI app on your computer (Claude Desktop, Cursor, VS Code, any MCP client) read a lawyer's case calendar: deadlines, hearings and tasks with a due day, across their active cases. Dates come in both Gregorian and Jalali (Persian) form, and "today" is Iran's day. It also converts dates between the two calendars without any account.

Read only. The server cannot create, change or delete anything.

Tools

Tool Needs the API What it returns
get_calendar(start, end, mine_only?) yes Items due from start to end (both included, at most 62 days), plus overdue items. Dates as YYYY-MM-DD or Jalali YYYY/MM/DD, Persian digits accepted
get_upcoming(days?, mine_only?) yes Today (Iran) and the next days; days 1–62, default 7
get_overdue(mine_only?) yes Open items due in the last 90 days that are not done (overdue, overdue_total)
today() no Today in Iran, Gregorian and Jalali, with the weekday
convert_date(value) no Jalali ↔ Gregorian conversion

mine_only keeps deadlines and only the tasks assigned to the signed-in lawyer. today and convert_date run locally and send nothing over the network.

Setup

Add the server to your MCP client. For Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "jalali-calendar": {
      "command": "uvx",
      "args": ["jalali-calendar-mcp"],
      "env": {
        "JALALI_CALENDAR_URL": "https://your-calendar-service.example",
        "JALALI_CALENDAR_TOKEN": "your-calendar-token"
      }
    }
  }
}

Or install it with pip install jalali-calendar-mcp and use "command": "jalali-calendar-mcp".

Variable Meaning
JALALI_CALENDAR_URL Address of the calendar API. Must be https; plain http only for localhost
JALALI_CALENDAR_TOKEN A read-only calendar token from that service

Set both, or neither: without them only today and convert_date work.

The calendar API it reads

GET {JALALI_CALENDAR_URL}/api/v1/calendar?from=YYYY-MM-DD&to=YYYY-MM-DD with Authorization: Bearer <token>, answering:

{
  "from": "2026-11-21", "to": "2026-11-27", "today": "2026-11-21", "truncated": false,
  "items": [
    {"type": "deadline", "id": "…", "title": "…", "due_on": "2026-11-22", "done": false,
     "kind": "hearing", "due_time": "09:30:00", "note": "…", "mine": false,
     "case": {"id": "…", "number": "1405-042", "display_title": "…"}},
    {"type": "task", "id": "…", "title": "…", "due_on": "2026-11-24", "done": false,
     "status": "in_progress", "mine": true, "case": {"id": "…", "number": "1405-042"}}
  ],
  "overdue": [], "overdue_total": 0
}

The range is at most 62 days. note and the case title may be left out. Errors use {"code": "…"} with codes such as invalid_token, invalid_input and rate_limited.

Privacy

What a tool returns goes to your AI app and, from there, to that app's model provider. A case calendar holds client data, so decide whether that is acceptable for your practice before connecting it. Prefer a token that shares only case numbers, not titles or notes, and revoke it when you stop using it.

The server sends the token only to JALALI_CALENDAR_URL, never follows redirects and never puts the token in errors. Titles and notes are case data; the server tells the model to treat them as data, not instructions.

As a library

from datetime import date
from jalali_calendar_mcp import CalendarApiClient, jalali, parse_date

client = CalendarApiClient("your-calendar-token", base_url="https://your-calendar-service.example")
calendar = await client.calendar(date(2026, 11, 21), date(2026, 11, 27))
parse_date("۱۴۰۴/۰۱/۰۱")  # date(2025, 3, 21)

Development

uv sync
uv run ruff check . && uv run ruff format --check .
uv run pytest

فارسی

این سرور MCP به دستیار هوش مصنوعی روی رایانهٔ شما (مثل Claude Desktop) اجازه می‌دهد تقویم پرونده‌های یک وکیل را فقط بخواند: مهلت‌ها، جلسه‌ها و کارهای سررسیددار پرونده‌های فعال، با تاریخ شمسی و میلادی. هیچ چیزی را نمی‌سازد، تغییر نمی‌دهد یا حذف نمی‌کند. تبدیل تاریخ شمسی و میلادی و «امروز» به وقت ایران بدون حساب کاربری هم کار می‌کند.

۱. نشانی سرویس تقویم را در JALALI_CALENDAR_URL و توکن فقط‌خواندنی آن را در JALALI_CALENDAR_TOKEN بگذارید (نمونهٔ بالا). ۲. سرور را به برنامهٔ هوش مصنوعی خود اضافه کنید.

حریم خصوصی: آنچه این ابزارها برمی‌گردانند به برنامهٔ هوش مصنوعی شما و ارائه‌دهندهٔ مدل آن فرستاده می‌شود. پیش از اتصال، دربارهٔ محرمانگی اطلاعات پرونده‌ها تصمیم بگیرید و توکن را هر زمان که لازم نبود باطل کنید.

License

MIT

Metadata

Release files for jalali-calendar-mcp 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jalali-calendar-mcp 0.1.0
File Size Uploaded Provenance Actions
jalali_calendar_mcp-0.1.0.tar.gz 14.0 kB Without provenance Details for jalali_calendar_mcp-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for jalali-calendar-mcp 0.1.0
File Interpreter ABI Platform Actions
jalali_calendar_mcp-0.1.0-py3-none-any.whl Python 3 none any Details for jalali_calendar_mcp-0.1.0-py3-none-any.whl

Total release size: 27.4 kB

Release files / jalali_calendar_mcp-0.1.0.tar.gz

Download URL jalali_calendar_mcp-0.1.0.tar.gz
Size 14.0 kB
Tags Source
SHA-256 checksum
How to use checksums
b059bf3d6ea5dc206cc8f554d521dcffdb24e283b2babd072f92f6d4b2e72193
BLAKE2b-256 checksum
How to use checksums
2221038d9f96e4ec87afbbc709a4dc080bbcd663640803946b9bb0e0d5cb51f1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / jalali_calendar_mcp-0.1.0-py3-none-any.whl

Download URL jalali_calendar_mcp-0.1.0-py3-none-any.whl
Size 13.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0549565008ac238cea13099e54eaf889778e75d09d71d66f29d698d02ad9b9af
BLAKE2b-256 checksum
How to use checksums
9621e61e8bd584e3391c309158e7e3bb2dfca89801e1b8abe58ab04d996f5a88
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.9 {"installer":{"name":"uv","version":"0.13.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for jalali-calendar-mcp 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page