MCP Time Server

MCP Time Server is a Model Context Protocol (MCP) server that provides date, time, timezone, calendar, duration, and time-calculation tools to AI assistants and MCP-compatible clients.

It runs over stdio, making it suitable for local MCP clients such as LM Studio and other MCP-compatible applications.

Features

• Current date and time
• Date formatting
• Date parsing
• Date arithmetic
• Date difference calculations
• Start/end boundaries
• Date validation
• Date comparisons
• Date-range checks
• Relative time
• Duration calculations
• Timezone conversion
• UTC operations
• Unix timestamp conversion
• Week and quarter calculations
• Leap-year predicates
• Minimum/maximum date lookup
• Locale metadata
• Working-day calculations
• Age calculations
• Day-of-week information
• Local runtime time
• World-time lookup
• Time-of-day duration calculations
• Time-of-day arithmetic

The server exposes the datetime functionality through a unified MCP tool registry.

MCP Client Configuration

LM Studio

Add the server to your MCP configuration.

Using npx

{
  "mcpServers": {
    "mcptimeserver": {
      "command": "npx",
      "args": [
        "-y",
        "@brainycalc/mcptimeserver"
      ]
    }
  }
}

If your published package name is different, replace mcptimeserver with the actual npm package name.

Using the local source

{
  "mcpServers": {
    "mcptimeserver": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcptimeserver/src/index.js"
      ]
    }
  }
}

Use an absolute path for the local installation.

MCP Architecture

The server is built around the Model Context Protocol SDK.

The main server:

src/index.js

The date/time implementation:

src/datetime.js

The server imports:

import { datetimeTools } from "./datetime.js";

All datetime tools are collected into one registry:

const ALL_TOOLS = [
  ...datetimeTools
];

A map is then created for fast tool lookup:

const toolMap = new Map(
  ALL_TOOLS.map((tool) => [tool.name, tool])
);

The MCP server implements:

• ListTools
• CallTool

and communicates through:

StdioServerTransport

Available MCP Tools

The current package contains 27 datetime tools.

| Tool | Description | |---|---| | now | Get the current date and time | | format_date | Format a date/time using a custom format | | parse_date | Parse a date and return structured components | | adjust_time | Add or subtract time | | date_diff | Calculate the difference between two dates | | boundary_of | Get the start or end of a time unit | | is_valid | Validate a date | | compare_dates | Compare two dates | | is_between | Check whether a date is between two dates | | relative_time | Return human-readable relative time | | duration | Create and inspect durations | | convert_timezone | Convert a date/time between timezones | | days_in_month | Get the number of days in a month | | unix_convert | Convert dates to/from Unix timestamps | | date_part | Get week, quarter, day-of-year, or weekday information | | date_predicate | Test leap-year/today/tomorrow/yesterday | | min_max | Find the earliest or latest date | | to_representation | Convert a date to another representation | | locale_data | Get month/weekday locale information | | utc_date | Parse or convert dates in UTC mode | | work_days | Calculate working days | | calc_age | Calculate age | | day_of_week | Get weekday and calendar information | | local_time | Get local runtime time | | world_time | Look up time around the world | | time_duration | Calculate duration between two times | | time_add | Add/subtract hours, minutes, and seconds |

License

MIT License.

See the LICENSE file for the complete license text.

Documentations and Help

• Documentation

Keywords

Recommended npm keywords:

mcp
mcp-server
model-context-protocol
time
date
datetime
timezone
utc
calendar
date-calculator
time-calculator
unix-timestamp
duration
ai
ai-agent
llm
lm-studio
nodejs
javascript