get_datetime
Retrieve the current date and time in multiple formats including ISO 8601, Unix timestamp, and individual components. Optionally specify a timezone for localized results.
Instructions
Get the current date and time in various formats.
Returns:
ISO 8601 string
Unix timestamp
Individual components (year, month, day, hour, minute, second)
Day of week and week number
Timezone information
This tool does not require any parameters.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| timezone | No | IANA timezone string (e.g., 'America/New_York', 'UTC'). Defaults to the server's local timezone. |
Implementation Reference
- src/tools/datetime.ts:31-101 (handler)The async handler function that executes the get_datetime tool logic. Creates a Date object, formats it with optional timezone, computes components (year, month, day, hour, minute, second, millisecond), day of week, week number, timezone, and UTC offset, then returns JSON output. Includes try/catch error handling.
async ({ timezone }) => { try { const now = new Date(); // Build timezone suffix for formatting const tzSuffix = timezone ? ` ${timezone}` : ""; const formatted = timezone ? now.toLocaleString("en-US", { timeZone: timezone }) : now.toLocaleString("en-US"); const dayNames = [ "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", ]; // Get the start of the year for week number calculation const startOfYear = new Date(now.getFullYear(), 0, 1); const pastDaysOfYear = (now.getTime() - startOfYear.getTime()) / 86_400_000; const weekNumber = Math.ceil( (pastDaysOfYear + startOfYear.getDay() + 1) / 7 ); return { content: [ { type: "text" as const, text: JSON.stringify( { iso8601: now.toISOString(), unixTimestamp: Math.floor(now.getTime() / 1000), unixTimestampMs: now.getTime(), formatted: formatted + tzSuffix, components: { year: now.getFullYear(), month: now.getMonth() + 1, day: now.getDate(), hour: now.getHours(), minute: now.getMinutes(), second: now.getSeconds(), millisecond: now.getMilliseconds(), }, dayOfWeek: dayNames[now.getDay()], weekNumber, timezone: timezone || Intl.DateTimeFormat().resolvedOptions().timeZone, utcOffset: `UTC${now.getTimezoneOffset() > 0 ? "-" : "+"}${String(Math.abs(Math.floor(now.getTimezoneOffset() / 60))).padStart(2, "0")}:${String(Math.abs(now.getTimezoneOffset() % 60)).padStart(2, "0")}`, }, null, 2 ), }, ], }; } catch (err: any) { return { content: [ { type: "text" as const, text: `DateTime Error: ${err.message}`, }, ], isError: true, }; } } ); - src/tools/datetime.ts:23-30 (schema)Input schema for the get_datetime tool: an optional 'timezone' string parameter (IANA timezone like 'America/New_York' or 'UTC'), described using Zod.
{ timezone: z .string() .optional() .describe( "IANA timezone string (e.g., 'America/New_York', 'UTC'). Defaults to the server's local timezone." ), }, - src/tools/datetime.ts:10-102 (registration)The registerDateTimeTool function that registers 'get_datetime' on the MCP server via server.tool(). Includes tool name, description, input schema, and the handler.
export function registerDateTimeTool(server: McpServer): void { server.tool( "get_datetime", `Get the current date and time in various formats. Returns: - ISO 8601 string - Unix timestamp - Individual components (year, month, day, hour, minute, second) - Day of week and week number - Timezone information This tool does not require any parameters.`, { timezone: z .string() .optional() .describe( "IANA timezone string (e.g., 'America/New_York', 'UTC'). Defaults to the server's local timezone." ), }, async ({ timezone }) => { try { const now = new Date(); // Build timezone suffix for formatting const tzSuffix = timezone ? ` ${timezone}` : ""; const formatted = timezone ? now.toLocaleString("en-US", { timeZone: timezone }) : now.toLocaleString("en-US"); const dayNames = [ "Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", ]; // Get the start of the year for week number calculation const startOfYear = new Date(now.getFullYear(), 0, 1); const pastDaysOfYear = (now.getTime() - startOfYear.getTime()) / 86_400_000; const weekNumber = Math.ceil( (pastDaysOfYear + startOfYear.getDay() + 1) / 7 ); return { content: [ { type: "text" as const, text: JSON.stringify( { iso8601: now.toISOString(), unixTimestamp: Math.floor(now.getTime() / 1000), unixTimestampMs: now.getTime(), formatted: formatted + tzSuffix, components: { year: now.getFullYear(), month: now.getMonth() + 1, day: now.getDate(), hour: now.getHours(), minute: now.getMinutes(), second: now.getSeconds(), millisecond: now.getMilliseconds(), }, dayOfWeek: dayNames[now.getDay()], weekNumber, timezone: timezone || Intl.DateTimeFormat().resolvedOptions().timeZone, utcOffset: `UTC${now.getTimezoneOffset() > 0 ? "-" : "+"}${String(Math.abs(Math.floor(now.getTimezoneOffset() / 60))).padStart(2, "0")}:${String(Math.abs(now.getTimezoneOffset() % 60)).padStart(2, "0")}`, }, null, 2 ), }, ], }; } catch (err: any) { return { content: [ { type: "text" as const, text: `DateTime Error: ${err.message}`, }, ], isError: true, }; } } ); } - src/index.ts:53-57 (registration)Call to registerDateTimeTool(this.server) inside registerTools() to wire up the tool on the MCP server instance.
registerDateTimeTool(this.server); registerJsonParserTool(this.server); registerTextTransformTool(this.server); registerEnvironmentTool(this.server); } - src/tools/datetime.ts:51-57 (helper)Week number calculation helper logic inside the handler (computes week of year using start-of-year date arithmetic).
// Get the start of the year for week number calculation const startOfYear = new Date(now.getFullYear(), 0, 1); const pastDaysOfYear = (now.getTime() - startOfYear.getTime()) / 86_400_000; const weekNumber = Math.ceil( (pastDaysOfYear + startOfYear.getDay() + 1) / 7 );