Skip to main content
Glama
local-time-mcp

local-time-mcp

🕐 local-time-mcp

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

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

Python 3.11+ License: MIT


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

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

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


Related MCP server: date

✨ امکانات

امکان

توضیح

🌍 هر 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


Available Tools

1 tool
get_current_datetimeA

Get the current date and time.

Returns structured JSON with the current datetime, including:

  • ISO 8601 datetime string

  • Date (YYYY-MM-DD)

  • Time (HH:MM:SS)

  • Day of week in English and Persian

  • IANA timezone name

  • UTC offset

  • Unix timestamp

  • Jalali (Solar Hijri) date in numeric and Persian formats

Args: timezone: Optional IANA timezone name (e.g., "Asia/Tehran", "Europe/Berlin", "America/New_York", "UTC"). If not provided, uses system local timezone.

Returns: JSON string with datetime information, or error message for invalid timezone.

Examples: - get_current_datetime() -> Current time in system timezone - get_current_datetime("Asia/Tehran") -> Current time in Tehran - get_current_datetime("UTC") -> Current time in UTC

Inputs: timezone. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only a single tool exists, so there is no possibility of overlap or confusion. The tool's purpose is clearly defined.

    Naming Consistency5/5

    The single tool follows a clear verb_noun pattern (get_current_datetime), which is consistent and descriptive.

    Tool Count3/5

    With only 1 tool, the server feels thin even for a focused time utility. However, the tool provides comprehensive datetime information, making the single tool non-trivial.

    Completeness5/5

    For its scope (returning current datetime with optional timezone), the tool fully covers the domain. It returns all relevant fields including ISO, date, time, day of week, timezone, offset, Unix timestamp, and Jalali date.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      The Time MCP Server is a Model Context Protocol (MCP) server that provides AI assistants and other MCP clients with standardized tools to perform time and date-related operations. This server acts as a bridge between AI tools and a robust time-handling back
      112 npm
      25
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that provides real-time date, time and time zone information for AI assistants.
      4
      2
      Apache 2.0
    • A
      license
      D
      quality
      C
      maintenance
      A lightweight MCP server that provides date and time tools, including the ability to retrieve current timestamps and parse date strings with IANA timezone support. It enables AI models to interact with the host OS clock and perform temporal calculations via stdio transport.
      3
      11 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Lightweight MCP server providing system time tools (current time, date, datetime, time components, unix timestamp) for LLM applications.
      1
      MIT