Skip to main content

​
Summary

The Time Utilities MCP server provides time and date tools for AI assistants. Get the current time, parse relative time expressions like “yesterday” or “3 days ago”, and list valid timezone identifiers. No authentication required.

​
Authentication

No authentication required. This server is publicly accessible. 
# No auth needed
curl https://app.chatbotplatform.io/mcp/time/call/today

​
Use Cases

​
Context-Aware Date Filtering

User: “Show me last week’s conversation archives” Tool Calls:
  1. relative-time with expression “last week” → Returns date range (start_date, end_date)
  2. Use date range to filter archives
Result: Archives filtered to last week’s date range

​
Timezone-Aware Scheduling

User: “What time is it in Tokyo right now?” Tool Calls:
  1. now with timezone “Asia/Tokyo” → Returns current time in Tokyo with offset
Result: “It’s 3:45 PM JST (UTC+9) in Tokyo”

​
Natural Language Date Parsing

User: “Get the data from 3 days ago” Tool Calls:
  1. relative-time with expression “3 days ago” → Returns specific date in YYYY-MM-DD format
Result: Date converted to “2026-02-01” (if today is 2026-02-04)

​
Available Tools

​
now

Returns the current time with high precision.
ParameterTypeRequiredDescription
timezonestringNoTimezone identifier (default: “UTC”). Examples: “America/New_York”, “Europe/London”, “Asia/Tokyo”
Returns:
  • ISO 8601 timestamp
  • Current date and time (24h and 12h formats)
  • Timezone name and UTC offset
  • Unix timestamp and milliseconds
Example: 
Input: timezone: "America/New_York"
Output:
  ISO 8601: 2026-02-04T10:30:45-05:00
  Date: 2026-02-04
  Time: 10:30:45 (10:30:45 AM)
  Timezone: America/New_York (EST)
  UTC Offset: -05:00
  Unix: 1738683045
  Milliseconds: 1738683045000
Use Cases: Timestamping events, calculating durations, time-sensitive operations

​
today

Returns the current date with quick reference dates.
ParameterTypeRequiredDescription
timezonestringNoTimezone identifier (default: “UTC”)
Returns:
  • Today’s date in YYYY-MM-DD format
  • Full formatted date (e.g., “Tuesday, February 4, 2026”)
  • Current time
  • Timezone and UTC offset
  • Quick reference dates (yesterday, start of week, start of month, 7 days ago, 30 days ago)
Example: 
Input: timezone: "UTC"
Output:
  Today: 2026-02-04
  Formatted: Tuesday, February 4, 2026
  Time: 15:30:45
  Timezone: UTC (UTC+00:00)

  Quick Reference:
  - Yesterday: 2026-02-03
  - Start of Week: 2026-02-02
  - Start of Month: 2026-02-01
  - 7 Days Ago: 2026-01-28
  - 30 Days Ago: 2026-01-05
Use Cases: Date-aware queries, filtering by date ranges, determining current date context

​
relative-time

Converts natural language time expressions to YYYY-MM-DD format.
ParameterTypeRequiredDescription
expressionstringYesRelative time expression (e.g., “yesterday”, “3 days ago”, “last week”)
timezonestringNoTimezone identifier (default: “UTC”)
Supported Expressions: Direct Dates:
  • yesterday → 2026-02-03
  • today → 2026-02-04
  • tomorrow → 2026-02-05
  • day before yesterday → 2026-02-02
Relative Offsets:
  • 3 days ago → 2026-02-01
  • 2 weeks ago → 2026-01-21
  • 1 month ago → 2026-01-04
Date Ranges:
  • last week → Start: 2026-01-27, End: 2026-02-02
  • last month → Start: 2026-01-01, End: 2026-01-31
  • last year → Start: 2025-01-01, End: 2025-12-31
  • this week → Start: 2026-02-02, End: 2026-02-08
  • this month → Start: 2026-02-01, End: 2026-02-28
  • this year → Start: 2026-01-01, End: 2026-12-31
Returns: Single date or date range in YYYY-MM-DD format with full formatted date and timezone info. Examples: 
Input: "3 days ago"
Output: 2026-02-01 (Sunday, February 1, 2026)

Input: "last week"
Output:
  Start: 2026-01-27 (Monday, January 27, 2026)
  End: 2026-02-02 (Sunday, February 2, 2026)
Fallback Parsing: If an expression doesn’t match the patterns above, the tool uses Carbon’s natural language parser for additional flexibility.

​
timezones

Lists all valid timezone identifiers supported by the system.
ParameterTypeRequiredDescription
regionstringNoFilter by region: “Africa”, “America”, “Antarctica”, “Arctic”, “Asia”, “Atlantic”, “Australia”, “Europe”, “Indian”, “Pacific”, “UTC”
searchstringNoSearch timezones by name (case-insensitive, e.g., “New_York”, “London”, “Tokyo”)
Returns: Timezone identifiers organized by region with current UTC offset for each. Example: 
Input: region: "America", search: "New"
Output:
  America:
  - America/New_York (UTC-05:00)
  - America/North_Dakota/New_Salem (UTC-06:00)
All Regions:
  • Africa (e.g., Africa/Cairo, Africa/Johannesburg)
  • America (e.g., America/New_York, America/Los_Angeles, America/Chicago)
  • Antarctica (e.g., Antarctica/McMurdo)
  • Arctic (e.g., Arctic/Longyearbyen)
  • Asia (e.g., Asia/Tokyo, Asia/Dubai, Asia/Shanghai)
  • Atlantic (e.g., Atlantic/Azores, Atlantic/Reykjavik)
  • Australia (e.g., Australia/Sydney, Australia/Melbourne)
  • Europe (e.g., Europe/London, Europe/Paris, Europe/Berlin)
  • Indian (e.g., Indian/Maldives)
  • Pacific (e.g., Pacific/Auckland, Pacific/Fiji)
  • UTC
Use Cases: Validating user timezone input, listing options for timezone selection, timezone conversion

​
Common Workflows

​
Date-Based Archive Filtering

1

Determine Current Date

Use today to establish context
2

Parse User's Date Expression

Use relative-time to convert “last week” to date range
3

Filter Archives

Use the YYYY-MM-DD dates with the archive filtering API

​
Timezone-Aware Reminders

1

Find User's Timezone

Use timezones with search to find valid timezone identifier
2

Get Current Time

Use now with user’s timezone to show current time
3

Create Reminder

Use timezone identifier when creating reminder

​
Time-Sensitive Context

1

Establish Current Date

Use today to determine true current date
2

Parse Relative Expressions

Use relative-time for user requests like “data from yesterday”
3

Apply to Queries

Use the standardized YYYY-MM-DD dates in subsequent tool calls

​
Tips & Best Practices

  • Always check the current date first using today before making time-based queries to ensure accuracy
  • Use YYYY-MM-DD format for consistency across all date filtering and storage
  • Specify timezones explicitly when dealing with user scheduling to avoid confusion
  • Validate timezone identifiers using timezones tool before accepting user input
  • Date ranges are inclusive - “last week” includes both start and end dates

​
Integration with Other Tools

​
With Conversation Archives

1. today → Get current date context
2. relative-time("last month") → Get date range
3. list-archives(start_date, end_date) → Filter archives

​
With Reminders

1. timezones(search: "New_York") → Validate timezone
2. now(timezone: "America/New_York") → Show current time
3. create-reminder(scheduled_at, timezone) → Create timezone-aware reminder

API Reference

View the complete API specification for Time Utilities MCP server endpoints