> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatbotplatform.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Time Utilities MCP Server
> Current time, date utilities, relative time parsing, and timezone conversion for AI assistants.
## 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.
```bash theme={null}
# 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.
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | -------------------------------------------------------------------------------------------------- |
| `timezone` | string | No | Timezone 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.
| Parameter | Type | Required | Description |
| ---------- | ------ | -------- | ------------------------------------ |
| `timezone` | string | No | Timezone 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.
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | ----------------------------------------------------------------------- |
| `expression` | string | Yes | Relative time expression (e.g., "yesterday", "3 days ago", "last week") |
| `timezone` | string | No | Timezone 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.
| Parameter | Type | Required | Description |
| --------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `region` | string | No | Filter by region: "Africa", "America", "Antarctica", "Arctic", "Asia", "Atlantic", "Australia", "Europe", "Indian", "Pacific", "UTC" |
| `search` | string | No | Search 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
Use `today` to establish context
Use `relative-time` to convert "last week" to date range
Use the YYYY-MM-DD dates with the archive filtering API
### Timezone-Aware Reminders
Use `timezones` with search to find valid timezone identifier
Use `now` with user's timezone to show current time
Use timezone identifier when creating reminder
### Time-Sensitive Context
Use `today` to determine true current date
Use `relative-time` for user requests like "data from yesterday"
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
```
***
View the complete API specification for Time Utilities MCP server endpoints