Vreme Temporal MCP Server

v1.9.9

MCP server providing comprehensive temporal intelligence including timezone conversions, 32 cultural calendars, astronomical events, prayer times, 247+ country holiday data, 5 financial markets, business time calculations, astrology, observance tracking, timezone offset intelligence, date range operations, historical date facts, temporal pattern detection, weekday finder, business days calculator, nth occurrence finder, and time in timezone calculator.

What's New in v1.9.9

Time in Timezone Calculator - 1 new tool for timezone conversions:

calculate_time_in_timezone - Convert a datetime to a specific timezone and return structured data about what that time is in that timezone. Returns local datetime, date, time, UTC offset, DST status, timezone abbreviation, and day-of-week metadata. Perfect for queries like "What is 3pm EST in Tokyo time?" or "Convert this datetime to New York timezone". Handles timezone-aware and naive datetimes.

All tools return structured JSON data only (no formatted strings), following Vreme's data-first philosophy. Fast execution, pure computational facts.

Overview

Vreme Temporal MCP Server provides 67 specialized tools for temporal intelligence, organized into 15 categories:

Core Temporal Tools (7) - Time queries, prayer times, activity appropriateness
Holiday & Business Time (10) - 247+ countries, business day calculations
Advanced Temporal Processing (18) - Time arithmetic, phrase resolution, conflict checking, duration calculations
Calendar & Recurrence (4) - Multi-calendar alignment, RRULE expansion
Fuzzy Time (3) - Uncertain time representations
Astronomical (7) - Sunrise/sunset, zodiac, moon phases
Observances & Cultural (3) - Awareness days, tech holidays, commemorations
Duration & Period (5) - Duration calculations, period analysis, age calculations
Timezone Offset (3) - Timezone offset calculations, DST transitions, timezone metadata
Date Range Operations (3) - Date range overlap detection, containment checks, set operations
Historical & Projection (2) - Historical day of week facts, date projections
Temporal Pattern Detection (2) - Pattern detection (daily/weekly/monthly/yearly), frequency analysis
Weekday Finder (1) - Find next/previous/closest weekday from reference date
Business Days Calculator (1) - Calculate business days between two dates
Nth Occurrence Finder (1) - Find nth occurrence of weekday in month/year
Time in Timezone Calculator (1) - Convert datetime to specific timezone

Tools Reference

Core Temporal Tools

get_temporal_context - Provides real-time temporal awareness. Call before every response to get current time, date, timezone, time of day, and activity tracking. No parameters required.

get_current_time - Get current time, date, and timezone information. Use when user asks 'What time is it?' or when writing dates in code/docs/changelogs. Returns ISO datetime, timezone, day_of_week, date_string, time_string, time_of_day. No parameters required.

query_time - Natural language queries about time, calendars, and observances. Use for: 'What time is it in Tokyo?', 'When is Ramadan?', 'Is it Diwali?', 'What's the moon phase?'. Returns rich context including calendars, astronomical events, and cultural observances.

query_prayer_times - Get precise Islamic prayer times (Salah/Namaz) for any location. Returns all 5 daily prayers (Fajr, Dhuhr, Asr, Maghrib, Isha), next prayer countdown, and Qibla direction to Mecca.

check_activity_appropriateness - Check if it's appropriate to call/work/meet with someone right now. Considers time of day, cultural observances (Shabbat, Ramadan fasting), religious work restrictions, and local customs across calendar systems.

analyze_temporal_context - Get comprehensive analysis of a specific date including all calendar representations, cultural observances, astronomical events, business context, seasonal info, and temporal density score (0-100 significance).

compare_dates - Compare two dates to understand temporal distance and significance. Returns time difference, observances on each date, shared observances, and which is more culturally significant.

Holiday and Business Time

calculate_business_time - Arithmetic with business days/hours, accounting for weekends and holidays. Operations: add_days, days_between, hours_between, is_working_day.

list_holiday_countries - List all 247+ countries with holiday data support. Returns country codes and names.

get_country_holidays - Get all holidays for a country in a specific year. Returns every holiday with dates, names, and categories (PUBLIC, BANK, SCHOOL, OPTIONAL). Can filter by categories. Fast: <30ms.

check_holiday - Check if a date is a PUBLIC holiday (government closure) in a country. Returns holiday name if yes, or null if no. Fastest holiday tool (<10ms).

list_financial_markets_holidays - List all 5 supported financial markets with trading holiday calendars. Returns: XNYS (NYSE), XNSE (NSE India), BVMF (Brazil), XECB (ECB TARGET2), IFEU (ICE Futures Europe).

get_market_holidays - Get all trading holidays when a financial market is closed. Use for: 'When is NYSE closed in 2024?', 'What are NSE India trading holidays?'. Markets: XNYS, XNSE, BVMF, XECB, IFEU. Fast: <20ms.

check_business_day - Check if a date is a working day (not holiday AND not weekend). Returns Yes/No with detailed reason. Prefer this over check_holiday when user asks about 'business day' or 'working day'. Fast: <10ms.

validate_date - Validate if a date is valid (e.g., catch Feb 30, Month 13). Returns detailed errors and smart suggestions for fixes. Checks leap years, month boundaries, etc. Fast: <5ms.

add_business_days_detailed - Add/subtract business days and get detailed metadata about what was excluded. Shows weekends skipped, holidays skipped, calendar span. Fast: <20ms.

resolve_relative_date - Convert expressions like 'next Monday', 'tomorrow', 'in 3 days' to actual dates. Uses simple, documented rules. Supports 'Elastic Tomorrow' for night coders (opt-in).

Advanced Temporal Processing

execute_time_arithmetic - Execute precise date/time math with business rules. Supports operations: add, subtract, set_time, set_date. Handles business_days with regional holiday calendars. Returns step-by-step execution trace with deterministic hashing.

resolve_temporal_phrase - Convert natural language phrases like 'tomorrow evening', 'end of week', 'early next week' to concrete time windows. Returns canonical window with start/end times, confidence score (0-1), and alternative interpretations.

compare_temporal_phrases - Compare two temporal phrases to analyze their relationship. Returns time difference, overlap analysis, which is earlier/later, and human-readable comparison.

export_temporal_context_snapshot - Export portable temporal context for Multi-LLM systems. Returns TemporalContextSnapshotV1 schema including current time, calendars, upcoming events, rhythm fingerprint, and optional artifacts.

generate_temporal_prompt_prefix - Convert temporal context snapshot to concise LLM-ready prompt prefix. Configurable max lines (default: 20). Optimized for system prompts.

check_good_moment_for_activity - Check if now is a good moment for activity. Activities: deep_work, financial_decision, hard_feedback, creative_play, exercise. Returns yes/no, score (0-1), reasons, and suggested alternative time.

check_temporal_conflicts - Analyze events for conflicts with holidays, weekends, sleep hours, work restrictions. Returns conflict analysis per event, overall risk level, summary. Multi-region holiday checking and sleep pattern analysis.

explain_time_behavior - Get simple explanations for complex time concepts. Topics: dst_transition (DST changes), business_days (how they work), timezone_difference (between two zones). Returns title, explanation, and key points.

analyze_global_sacred_time - Multi-region sacred time analysis for product launches, webinars, maintenance windows. Returns avoid windows (Ramadan, religious holidays), preferred windows. Supports religions: islam, christian, hindu, buddhist.

get_weekly_sacred_rhythm - Generate 7-day × 24-hour grid for multicultural teams. Shows aggregate scores for religious observances (Jumu'ah, Shabbat, Sunday worship) with severity scoring (0-1). Returns recommendations for recurring meetings.

get_microseason_context - Get seasonal micro-context for location and date. Returns microseason ID/name, day length, sunrise/sunset, description, suggested tone. Hemisphere-aware seasonal classification.

convert_time_scale - Convert between different time scales (Unix seconds, Unix millis, UTC ISO, Local ISO). Explicit timezone handling for local conversions. Batch conversion support.

list_time_scales - List all supported time scales with descriptions and examples. Shows: UNIX_SECONDS, UNIX_MILLIS, UTC_ISO, LOCAL_ISO (TAI, GPS planned).

Duration & Period

calculate_duration - Calculate structured duration between two timestamps. Returns total_seconds, days, hours, minutes, seconds as separate numeric fields. Use for calculating time differences, elapsed time, or duration between events.

calculate_period - Calculate weeks, months, quarters, or years between two dates. Returns structured data with days, weeks, months, quarters, and years as separate numeric fields. Handles leap years and month boundaries accurately.

age_from_birthdate - Calculate age as structured data from birthdate. Returns years, months, days, and total_days as separate numeric fields. Handles leap years and month boundaries accurately.

time_until - Calculate time until a future timestamp. Returns structured duration data (total_seconds, days, hours, minutes, seconds) and indicates if the time is in the past.

time_since - Calculate time since a past timestamp. Returns structured duration data (total_seconds, days, hours, minutes, seconds) and indicates if the time is in the future.

Timezone Offset

get_timezone_offset - Get offset between two timezones as structured data. Returns offset_seconds, offset_hours, is_dst status for both timezones, and DST transition information. Use for calculating time differences between timezones and understanding DST effects.

compare_timezones - Compare multiple timezones, return offset data for each pair. Returns structured comparison data showing offsets between all timezone pairs, current times in each timezone, and DST status.

get_timezone_info - Get timezone metadata including UTC offset, DST rules, and next/previous DST transitions. Returns structured data about timezone properties, current DST status, and transition information.

Date Range Operations

date_range_overlap - Check if two date ranges overlap and return overlap details. Returns boolean, overlap start/end dates, and overlap days count. Use for checking if two time periods overlap, finding common availability windows, or detecting scheduling conflicts.

date_range_contains - Check if a date is within a range and return position data. Returns boolean, position (start/end/middle/before/after), and days from start/end. Use for checking if a date falls within a period, finding relative position of dates, or validating date membership in ranges.

date_range_operations - Perform set operations on date ranges (union, intersection, difference). Returns merged result ranges with total days and count. Use for combining availability windows, finding common periods, or subtracting blocked time from available periods.

Historical & Projection

historical_day_of_week - Get day of week for a historical date as structured data. Returns day name, day number (0-6), ISO weekday (1-7), and weekend status. Use for finding what day of week a historical date fell on, checking weekend status, or analyzing temporal patterns.

project_date - Calculate future/past dates from a base date. Returns ISO timestamp (not formatted string). Use for calculating dates N days/months/years in the future or past, finding anniversary dates, or projecting deadlines. Handles leap years and month boundaries accurately.

Temporal Pattern Detection

detect_temporal_pattern - Analyze if dates follow a recurring pattern (daily, weekly, monthly, yearly) using proven statistical methods. Returns pattern type, confidence score, interval statistics, pattern details, and day-of-week information (for daily/weekly patterns, including weekday names and ISO weekdays). Use for identifying recurring events, validating schedule consistency, or analyzing temporal regularity.

calculate_frequency - Calculate frequency statistics of events over time. Returns events per day/week/month, interval statistics (average, min, max, median, std dev), regularity score, and time span details. Use for analyzing event frequency, calculating occurrence rates, or measuring temporal distribution.

Weekday Finder

find_weekday - Find the next, previous, or closest occurrence of a specific weekday from a reference date. Returns result date, days offset, and direction used. Accepts weekday names ("Monday") or numbers (0-6 or 1-7). Use for scheduling queries like "next Monday", "previous Friday", or "closest Wednesday".

Business Days Calculator

calculate_business_days_between - Calculate the number of business days between two dates, excluding weekends and public holidays. Returns structured count data including business days, calendar days, excluded weekends, and excluded holidays. Use for calculating working days between dates, SLA calculations, or deadline planning. Configurable inclusive/exclusive start/end dates.

Nth Occurrence Finder

find_nth_occurrence - Find the nth occurrence of a specific weekday in a month or year. Returns result date, occurrence number, and total occurrences in the period. Use for queries like "3rd Monday of January", "last Friday of 2024", or "2nd Tuesday of next month". Supports month-specific or year-wide searches, with optional business day checking.

Time in Timezone Calculator

calculate_time_in_timezone - Convert a datetime to a specific timezone and return structured data about what that time is in that timezone. Returns local datetime, date, time, UTC offset (seconds, hours, formatted), DST status, timezone abbreviation, and day-of-week metadata. Use for queries like "What is 3pm EST in Tokyo time?" or "Convert this datetime to New York timezone". Handles timezone-aware and naive datetimes.

Calendar and Recurrence

interval_operations - Perform set operations on time intervals. Operations: UNION (merge intervals), INTERSECTION (find overlap), DIFFERENCE (subtract), GAPS (find gaps). Handles overlapping and adjacent intervals with normalized output.

expand_recurrence - Expand RRULE recurrence patterns (RFC 5545) to concrete occurrences within time window. Supports full RRULE syntax (FREQ=WEEKLY;BYDAY=MO,WE,FR). Safety limit: max 1000 occurrences.

align_calendars - Show single chronological instant across multiple calendar systems. Supports: Gregorian, Unix, ISO Week, Ordinal (more planned: Islamic, Hebrew, Chinese).

find_partial_dates - Find all dates matching partial specification within search range. Search by year, month, day constraints.

Fuzzy Time

create_fuzzy_time_circa - Create fuzzy time representation from circa date expression with explicit uncertainty. Precision levels: year, month, day. Returns center point, window, confidence score (0-1). Use for 'circa 1990', historical dates with uncertainty.

create_fuzzy_time_window - Create fuzzy time from explicit time window with custom confidence scoring. Use for uncertain future events, flexible scheduling, time estimates. Returns center point, window bounds, confidence score.

intersect_fuzzy_times - Find intersection of two fuzzy times with refined confidence. When two uncertain time ranges overlap, this computes their intersection with combined confidence scoring.

Astronomical

get_astro_context - Get sunrise, sunset, day length, twilight times, and moon phase for a date and location. Returns solar noon, day length in hours, civil twilight boundaries, and current moon phase.

get_day_phase - Classify a timestamp into day phase (pre_dawn, morning, midday, afternoon, evening, night) based on solar position. Returns phase, sun above/below horizon, and time relative to sunrise/sunset.

get_season_context - Get hemisphere-aware seasonal classification for a date and location. Returns season (winter, spring, summer, autumn with early/late variants), hemisphere, day of year, and contextual notes.

get_zodiac_context - Get planet positions, zodiac signs, and aspects for a timestamp. Returns ecliptic longitudes, signs (with element/modality), and aspects (conjunction, opposition, trine, square, sextile) between bodies.

get_chinese_zodiac - Get Chinese zodiac animal, element, and 60-year cycle for a date. Returns lunar year, animal (Rat to Pig), element (Wood/Fire/Earth/Metal/Water), yin/yang, and cycle indices.

get_astro_events - Get astronomical events in a time window. Returns sun ingresses (Sun entering each zodiac sign) and moon phases (new, first quarter, full, last quarter) with precise UTC timestamps.

get_astro_calendar - Get astrology calendar for a date range in user's timezone. Returns sun ingresses and moon phases with local times and human-readable descriptions.

Observances and Cultural

get_observances_on_date - Get awareness days, fun days, commemorations, and cultural observances for a specific date. Categories: awareness_day, fun_day, tech, seasonal, commemoration, cultural, religious, corporate.

get_today_story - Get curated highlights for today - most relevant observances based on user's region and interests. Returns 1-3 observances with relevance scoring.

get_observances_calendar - Get calendar view of observances for a specific month. Returns all observances by day for planning and UI calendar displays.

Features

Global Holiday Intelligence

247+ countries with comprehensive holiday data
Category support: PUBLIC (government closures), BANK, SCHOOL, OPTIONAL
5 financial markets: NYSE, NSE India, Brazil B3, ECB TARGET2, ICE Futures Europe
Powered by python-holidays v0.86+

Cultural Calendars

32 calendar systems covering religious, cultural, and technical calendars:

Religious & Cultural: Hebrew, Islamic, Chinese, Hindu, Persian, Buddhist, Sikh, Coptic, Orthodox Christian, Ethiopian, Bahá'í, Thai Buddhist, Tibetan, Zoroastrian, Armenian, Javanese, Mongolian, Burmese

East Asian: Japanese, Bengali, Tamil, Nepali

Western & Technical: Mayan, Roman, French Revolutionary, Revised Julian, Discordian, Holocene, Unix Epoch, ISO Week Date, Western Zodiac, Star Trek Stardate

Coverage: 5+ billion people, 10+ religions, 300+ observances

Islamic Prayer Times

All 5 daily prayers: Fajr, Dhuhr, Asr, Maghrib, Isha
7 calculation methods: MWL, ISNA, Egypt, Makkah, Karachi, Tehran, Jafari
Qibla direction to Mecca
Next prayer countdown

Astronomical & Astrological Data

Sunrise, sunset, twilight times
Moon phases and lunar calendar
Western zodiac: planet positions, signs, aspects
Chinese zodiac: animal & element cycles
Sun ingresses and astronomical events

Installation

Quick Start

npx -y @vreme/temporal-mcp

Docker

docker pull vreme/temporal-mcp
docker run --rm -i vreme/temporal-mcp

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vreme": {
      "command": "npx",
      "args": ["-y", "@vreme/temporal-mcp"]
    }
  }
}

Docker configuration:

{
  "mcpServers": {
    "vreme": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "vreme/temporal-mcp"]
    }
  }
}

VS Code

Manual Configuration:

Open Command Palette (Ctrl + Shift + P) → MCP: Open User Configuration

Add to your mcp.json:

{
  "servers": {
    "vreme": {
      "command": "npx",
      "args": ["-y", "@vreme/temporal-mcp"]
    }
  }
}

VS Code MCP Documentation

Continue & Cline

Add to your MCP configuration following the respective setup guides.

Example Queries

Timezone & Time:

"What time is it in Tokyo?"
"Is it a good time to call London?"

Religious & Cultural:

"Is it Shabbat in Jerusalem?"
"When is Ramadan this year?"
"What are prayer times in Dubai?"

Holidays & Business:

"Is tomorrow a holiday in Germany?"
"Add 5 business days to December 20th"
"When is NYSE closed in 2025?"

Astronomical:

"When is sunrise in Paris?"
"What's the moon phase today?"
"What's my zodiac sign?"

Calendars:

"What's the Hebrew date today?"
"When is Chinese New Year?"
"Show me this date in the Islamic calendar"

Design Philosophy

Vreme focuses on temporal intelligence with a stateless, data-first architecture:

Stateless & Fast - No database queries, sub-100ms responses, infinitely scalable
Structured Data Only - JSON responses, no formatting or HTML, maximum composability
Factual & Authoritative - Verified holiday data, accurate calendar systems, trusted astronomical calculations
Focused Scope - Temporal data, calculations, and cultural calendars only. No scheduling, text generation, event storage, or notifications

Architecture

AI Client (Claude Desktop / VS Code / Continue / Cline)
    ↓ MCP Protocol
@vreme/temporal-mcp
    ↓ HTTPS
vreme.ai API
    ↓
Temporal Intelligence Engine

API Access

This MCP server is powered by the Vreme Time API.

Direct API usage:

curl -X POST https://api.vreme.ai/query \
  -H "Content-Type: application/json" \
  -d '{"query": "What time is it in Tokyo?"}'

Development

Build from Source

npm install
npm run build
npm link

Docker Build

docker build -t vreme/temporal-mcp .

Debugging

View MCP server logs:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

License

MIT License - see LICENSE file for details.

About Vreme

Vreme (Bulgarian: "time") builds temporal intelligence for AI systems. Our mission is to make AI temporally aware, understanding time, culture, and context across the globe.

@vreme/temporal-mcp

Quick Install