local-time-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@local-time-mcp What is the current time and Persian date?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
🕐 local-time-mcp
یک سرور MCP (Model Context Protocol) کوچک و قابل اعتماد که به عاملهای هوش مصنوعی اجازه میده زمان و تاریخ دقیق سیستم رو دریافت کنن — شامل تقویم جلالی (هجری شمسی).
🤖 Built with Claude Code — Anthropic's CLI for Claude.
🎯 چرا این پروژه؟
مدلهای زبانی (LLM) ساعت داخلی قابل اعتمادی ندارن. وقتی میپرسید «الان چند ساعته؟»، مدل یا از دادههای آموزشی حدس میزنه یا تاریخ ثابتی از system prompt میخونه — هر دو اشتباهه.
این سرور MCP این مشکل رو حل میکنه با دسترسی مستقیم به ساعت سیستم عامل در لحظه فراخوانی ابزار. هر پاسخ دقیق، بهروز و time-zone-aware هست.
Related MCP server: date
✨ امکانات
امکان | توضیح |
🌍 هر timezone IANA |
|
⏰ زمان دقیق | تاریخ، ساعت (با ثانیه)، Unix timestamp |
📅 تاریخ جلالی | عددی ( |
🇮🇷 نام روز و ماه فارسی | روز هفته به انگلیسی و فارسی |
🌗 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 IANA (مثلاً |
فیلدهای پاسخ
فیلد | نوع | مثال | توضیح |
|
|
| تاریخ و ساعت ISO 8601 با offset |
|
|
| تاریخ میلادی (YYYY-MM-DD) |
|
|
| ساعت (HH:MM:SS) |
|
|
| نام روز به انگلیسی |
|
|
| نام روز به فارسی |
|
|
| نام timezone IANA استفاده شده |
|
|
| اختلاف با UTC (±HH:MM) |
|
|
| Unix epoch timestamp |
|
|
| تاریخ جلالی (YYYY/MM/DD) |
|
|
| تاریخ جلالی به فارسی |
|
|
| سال جلالی |
|
|
| ماه جلالی (1-12) |
|
|
| نام ماه فارسی |
|
|
| روز جلالی (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/دستورات
دستور | توضیح | مثال |
| زمان فعلی با تمام جزئیات |
|
| زمان با timezone مشخص |
|
| تاریخ جلالی فعلی |
|
| روز هفته (انگلیسی + فارسی) |
|
| تبدیل میلادی به جلالی |
|
| تبدیل جلالی به میلادی |
|
| Unix timestamp |
|
| لیست timezoneهای رایج |
|
نمونه خروجی
{
"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 |
| زمان هماهنگ جهانی | +00:00 |
| ساعت ایران | +03:30 |
| ساعت مرکز اروپا (CET/CEST) | +01:00 / +02:00 |
| ساعت شرق آمریکا (EST/EDT) | -05:00 / -04:00 |
| ساعت اقیانوس آرام (PST/PDT) | -08:00 / -07:00 |
| ساعت ژاپن | +09:00 |
| ساعت بریتانیا (GMT/BST) | +00:00 / +01:00 |
| ساعت امارات | +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پوشش تستها
کلاس تست | تعداد | توضیح |
| ۶ | timezone محلی سیستم |
| ۳ | timezone آسیا/تهران |
| ۳ | timezone DST-aware |
| ۳ | timezone UTC |
| ۲ | timezone EST/EDT |
| ۳ | مدیریت خطا |
| ۴ | نام روز انگلیسی و فارسی |
| ۳ | محاسبات offset |
| ۲ | دقت timestamp |
| ۲ | بهروزرسانی بلادرنگ |
| ۳ | wrapper ابزار MCP |
| ۱۰ | تبدیل تقویم جلالی |
مجموع | ۴۴ |
🔍 عیبیابی
سرور MCP شروع نمیشه
# ۱. بررسی نسخه Python
python --version
# ۲. نصب مجدد وابستگیها
uv pip install -e .
# ۳. تست مستقیم سرور
python -m local_time_mcpخطای timezone نامعتبر
از نامهای timezone IANA معتبر استفاده کنید:
✅ درست | ❌ غلط |
|
|
|
|
|
|
|
|
مسائل مخصوص ویندوز
سرور روی Windows 10+ با Python 3.11+ کار میکنه
داده timezone از طریق ماژول
zoneinfoپایتون در دسترسهنیازی به پایگاه داده timezone اضافی نیست
📄 مجوز
Available Tools
1 toolget_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
Scored across 1 tool
Only a single tool exists, so there is no possibility of overlap or confusion. The tool's purpose is clearly defined.
The single tool follows a clear verb_noun pattern (get_current_datetime), which is consistent and descriptive.
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.
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
A real clock for AI agents: current time, timezone conversion, and DST facts from the IANA tzdb.
Current time, timezone conversion & date math for AI agents. On Cloudflare Workers.
MCP server for time in cities around the world, time zones, DST, conversion, and meetings.
A time server that keeps your AI honest about time. Real clock + drift guard, zero dependencies.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceThe 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 back112 npm25MIT
- AlicenseAqualityDmaintenanceAn MCP server that provides real-time date, time and time zone information for AI assistants.42Apache 2.0
- AlicenseDqualityCmaintenanceA 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.311 npm7MIT
- AlicenseNot gradedqualityDmaintenanceLightweight MCP server providing system time tools (current time, date, datetime, time components, unix timestamp) for LLM applications.1MIT