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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.