🕐 local-time-mcp

یک سرور MCP (Model Context Protocol) کوچک و قابل اعتماد که به عامل‌های هوش مصنوعی اجازه میده زمان و تاریخ دقیق سیستم رو دریافت کنن — شامل تقویم جلالی (هجری شمسی).

🤖 Built with Claude Code — Anthropic's CLI for Claude.

---

🎯 چرا این پروژه؟

مدل‌های زبانی (LLM) ساعت داخلی قابل اعتمادی ندارن. وقتی میپرسید «الان چند ساعته؟»، مدل یا از داده‌های آموزشی حدس میزنه یا تاریخ ثابتی از system prompt میخونه — هر دو اشتباهه.

این سرور MCP این مشکل رو حل می‌کنه با دسترسی مستقیم به ساعت سیستم عامل در لحظه فراخوانی ابزار. هر پاسخ دقیق، به‌روز و time-zone-aware هست.

---

✨ امکانات

امکان	توضیح
🌍 هر timezone IANA	Asia/Tehran, Europe/Berlin, America/New_York, UTC و غیره
⏰ زمان دقیق	تاریخ، ساعت (با ثانیه)، Unix timestamp
📅 تاریخ جلالی	عددی (1405/05/17) و فارسی (17 مرداد 1405)
🇮🇷 نام روز و ماه فارسی	روز هفته به انگلیسی و فارسی
🌗 DST خودکار	مدیریت خودکار CET/CEST, EST/EDT و غیره
🔌 کاملاً آفلاین	فقط از ساعت سیستم استفاده می‌کنه، بدون اتصال اینترنت
🪶 وابستگی‌های کم	Python 3.11+, MCP SDK, jdatetime, tzdata

---

📦 نصب و راه‌اندازی

پیش‌نیازها

• Python 3.11 یا بالاتر
• uv (توصیه شده) یا pip

نصب سریع

# کلون کردن مخزن
git clone https://github.com/karimi-mohammad/local-time-mcp.git
cd local-time-mcp

# نصب با uv (توصیه شده)
uv pip install -e .

# یا نصب با pip
pip install -e .

---

⚙️ پیکربندی Claude Code

روش ۱ — اضافه کردن از CLI (توصیه شده)

claude mcp add local-time -s user -- uv run --directory "C:\path\to\local-time-mcp" python -m local_time_mcp

روش ۲ — ویرایش دستی settings.json

این محتوا رو به فایل پیکربندی MCP Claude Code اضافه کنید (~/.claude/settings.json یا .claude/settings.json در سطح پروژه):

{
  "mcpServers": {
    "local-time": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\path\\to\\local-time-mcp",
        "python",
        "-m",
        "local_time_mcp"
      ]
    }
  }
}

روش ۳ — اجرای مستقیم Python (بعد از نصب)

cd local-time-mcp
pip install -e .

{
  "mcpServers": {
    "local-time": {
      "command": "local-time-mcp"
    }
  }
}

---

🔧 مرجع ابزار MCP

get_current_datetime

زمان و تاریخ فعلی رو به صورت JSON ساختاریافته برمی‌گردونه.

پارامتر	نوع	ضروری	توضیح
timezone	string	❌	نام timezone IANA (مثلاً Asia/Tehran, UTC). پیش‌فرض: ساعت محلی سیستم

فیلدهای پاسخ

فیلد	نوع	مثال	توضیح
datetime	string	2026-08-10T14:31:59+03:30	تاریخ و ساعت ISO 8601 با offset
date	string	2026-08-10	تاریخ میلادی (YYYY-MM-DD)
time	string	14:31:59	ساعت (HH:MM:SS)
day_of_week	string	Monday	نام روز به انگلیسی
day_of_week_fa	string	دوشنبه	نام روز به فارسی
timezone	string	Asia/Tehran	نام timezone IANA استفاده شده
utc_offset	string	+03:30	اختلاف با UTC (±HH:MM)
unix_timestamp	integer	1786359719	Unix epoch timestamp
jalali_date	string	1405/05/19	تاریخ جلالی (YYYY/MM/DD)
jalali_date_fa	string	19 مرداد 1405	تاریخ جلالی به فارسی
jalali_year	integer	1405	سال جلالی
jalali_month	integer	5	ماه جلالی (1-12)
jalali_month_name	string	مرداد	نام ماه فارسی
jalali_day	integer	19	روز جلالی (1-31)

نمونه استفاده

> get_current_datetime()
> get_current_datetime("Asia/Tehran")
> get_current_datetime("Europe/Berlin")
> get_current_datetime("UTC")
> get_current_datetime("America/New_York")

نمونه پاسخ

{
  "datetime": "2026-08-10T14:31:59+03:30",
  "date": "2026-08-10",
  "time": "14:31:59",
  "day_of_week": "Monday",
  "day_of_week_fa": "دوشنبه",
  "timezone": "Asia/Tehran",
  "utc_offset": "+03:30",
  "unix_timestamp": 1786359719,
  "jalali_date": "1405/05/19",
  "jalali_date_fa": "19 مرداد 1405",
  "jalali_year": 1405,
  "jalali_month": 5,
  "jalali_month_name": "مرداد",
  "jalali_day": 19
}

پاسخ خطا (timezone نامعتبر)

{
  "error": "Invalid timezone: 'Invalid/Zone'. Use IANA format like 'Asia/Tehran', 'UTC', etc."
}

---

🕐 اسکیل CLI local-time

علاوه بر MCP server، یک اسکیل CLI مستقل هم وجود داره که مستقیماً از خط فرمان قابل استفاده هست:

نصب اسکیل

# فایل‌ها رو به دایرکتوری skills کپی کنید
cp -r skill/ ~/.claude/skills/local-time/

دستورات

دستور	توضیح	مثال
now	زمان فعلی با تمام جزئیات	python local_time.py now
now --tz	زمان با timezone مشخص	python local_time.py now --tz Asia/Tehran
jalali	تاریخ جلالی فعلی	python local_time.py jalali
weekday	روز هفته (انگلیسی + فارسی)	python local_time.py weekday
to-jalali	تبدیل میلادی به جلالی	python local_time.py to-jalali 2026-08-10
to-gregorian	تبدیل جلالی به میلادی	python local_time.py to-gregorian 1405/05/19
timestamp	Unix timestamp	python local_time.py timestamp
timezones	لیست timezoneهای رایج	python local_time.py timezones

نمونه خروجی

{
  "datetime": "2026-08-10T14:31:59.027681+03:30",
  "date": "2026-08-10",
  "time": "14:31:59",
  "day_of_week": "Monday",
  "day_of_week_fa": "دوشنبه",
  "timezone": "Asia/Tehran",
  "utc_offset": "+03:30",
  "unix_timestamp": 1786359719,
  "jalali_date": "1405/05/19",
  "jalali_date_fa": "19 مرداد 1405"
}

---

🌍 timezoneهای پشتیبانی شده

هر نام timezone IANA معتبر کار می‌کنه. مثال‌های رایج:

Timezone	توضیح	UTC Offset
UTC	زمان هماهنگ جهانی	+00:00
Asia/Tehran	ساعت ایران	+03:30
Europe/Berlin	ساعت مرکز اروپا (CET/CEST)	+01:00 / +02:00
America/New_York	ساعت شرق آمریکا (EST/EDT)	-05:00 / -04:00
America/Los_Angeles	ساعت اقیانوس آرام (PST/PDT)	-08:00 / -07:00
Asia/Tokyo	ساعت ژاپن	+09:00
Europe/London	ساعت بریتانیا (GMT/BST)	+00:00 / +01:00
Asia/Dubai	ساعت امارات	+04:00

---

🤖 راهنمای استفاده برای عامل‌های هوش مصنوعی

Claude (یا هر عامل هوش مصنوعی متصل) باید در موارد زیر get_current_datetime رو فراخوانی کنه:

• 🕐 زمان یا تاریخ فعلی
• 📆 روز هفته
• 📛 "امروز"، "فردا"، "دیروز"
• ⏳ مهلت‌ها یا استدلال‌های حساس به زمان
• 📊 تاریخ‌های نسبی ("۲ روز دیگه")
• 🔄 هر عملیاتی که دقت در اون مهمه

از حدس زدن تاریخ/ساعت از context مدل استفاده نکنید. همیشه این ابزار رو فراخوانی کنید.

---

🧪 توسعه و تست‌ها

ساختار پروژه

local-time-mcp/
├── pyproject.toml              # پیکربندی پکیج
├── README.md                   # این فایل
├── LICENSE                     # مجوز MIT
├── src/
│   └── local_time_mcp/
│       ├── __init__.py
│       ├── __main__.py         # python -m local_time_mcp
│       └── server.py           # پیاده‌سازی سرور MCP
├── skill/
│   ├── SKILL.md                # مستندات اسکیل CLI
│   └── local_time.py           # اسکریپت CLI
└── tests/
    ├── __init__.py
    └── test_server.py          # ۴۴ تست

اجرای تست‌ها

# نصب وابستگی‌های توسعه
uv pip install -e ".[dev]"

# اجرای تمام تست‌ها
pytest

# اجرای با جزئیات
pytest -v

# اجرای یک کلاس تست خاص
pytest tests/test_server.py::TestJalaliDate -v

پوشش تست‌ها

کلاس تست	تعداد	توضیح
TestLocalTimezone	۶	timezone محلی سیستم
TestAsiaTehran	۳	timezone آسیا/تهران
TestEuropeBerlin	۳	timezone DST-aware
TestUTC	۳	timezone UTC
TestAmericaNewYork	۲	timezone EST/EDT
TestInvalidTimezone	۳	مدیریت خطا
TestDayOfWeek	۴	نام روز انگلیسی و فارسی
TestUTCOffset	۳	محاسبات offset
TestUnixTimestamp	۲	دقت timestamp
TestFreshTimestamp	۲	به‌روزرسانی بلادرنگ
TestMCPTool	۳	wrapper ابزار MCP
TestJalaliDate	۱۰	تبدیل تقویم جلالی
مجموع	۴۴

---

🔍 عیب‌یابی

سرور MCP شروع نمیشه

# ۱. بررسی نسخه Python
python --version

# ۲. نصب مجدد وابستگی‌ها
uv pip install -e .

# ۳. تست مستقیم سرور
python -m local_time_mcp

خطای timezone نامعتبر

از نام‌های timezone IANA معتبر استفاده کنید:

✅ درست	❌ غلط
Asia/Tehran	Tehran
Europe/Berlin	CET
America/New_York	EST
UTC	GMT (بعضی سیستم‌ها)

مسائل مخصوص ویندوز

• سرور روی Windows 10+ با Python 3.11+ کار می‌کنه
• داده timezone از طریق ماژول zoneinfo پایتون در دسترسه
• نیازی به پایگاه داده timezone اضافی نیست

---

📄 مجوز

MIT

---

<p align="center"> ساخته شده با ❤️ با استفاده از <a href="https://claude.ai/claude-code">Claude Code</a> </p>