MCP Time Server

You get a high-performance MCP server that lets you manipulate and format time across timezones, dates, and schedules for large language model workflows. It supports timezone conversions, current time lookups, date arithmetic, duration calculations, business days and hours, recurring events, and flexible formatting, all optimized with caching and rate limiting to keep responses fast and safe.

How to use

You use this MCP server with an MCP client by sending structured requests that describe the time operation you want to perform. Common workflows include converting times between timezones, adding or subtracting time from a date, calculating durations between timestamps, and determining business-related values like working hours or business days. Each operation is exposed as an MCP tool you can call with the required parameters. Use the output in your prompts, pipelines, or automation to drive decisions, scheduling, or analytics.

How to install

Prerequisites you need before installing:
- Node.js installed on your system (LTS version recommended)
- npm or npx available in your shell
- A supported MCP client or workflow that can call MCP endpoints or stdio servers

Follow these steps to install and prepare the time server for use.

# Install the MCP time server globally for easy access
npm install -g mcp-time-server-node

# Optional: build the project for local testing (if you clone the repo and work locally)
make build

# If you are testing locally with a CLI MCP client, you can start the server via npm/npx as shown below
npx -y mcp-time-server-node

# For local development and Claude Code integration, you can add the MCP server entry to Claude Code
claude mcp add tim-server /path/to/mcp-time-server-node/dist/index.js

# If you want to run the server via Claude Desktop configuration, you can configure it like this
# (This is an example config you would place in claude_desktop_config.json)
{
  "mcpServers": {
    "time-server": {
      "command": "npx",
      "args": ["-y", "mcp-time-server-node"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Additional setup details

The server exposes multiple tools (time-related operations) that you can call from your MCP client. If you are testing locally, you can build the project and run it with standard npm/npx workflows. The time server is designed to be fast, with intelligent caching and rate limiting to prevent abuse.

Environment and runtime notes

The server supports a set of environment variables to tune behavior. Common ones you may configure include NODE_ENV to production, RATE_LIMIT and RATE_LIMIT_WINDOW to control request throughput, CACHE_SIZE to bound cache, DEFAULT_TIMEZONE to override system detection, and MAX_LISTENERS to limit parallel requests.

Troubleshooting and tips

If you encounter time parsing or timezone issues, check that you are using valid IANA timezone names and that your input dates are in a parseable ISO-like format. If rate limits are hit, adjust RATE_LIMIT and RATE_LIMIT_WINDOW to suit your workload. For production deployments, ensure NODE_ENV is set to production to enable optimizations.

Available tools

get_current_time

Retrieve the current time in a specific timezone with optional formatting and offset inclusion.

convert_timezone

Convert a given time from one timezone to another and format the result.

add_time

Add a duration to a given date/time with a specific unit and optional timezone.

subtract_time

Subtract a duration from a given date/time with a specific unit and optional timezone.

calculate_duration

Compute the duration between two times with an optional unit and timezone.

get_business_days

Calculate the number of business days between two dates, with optional holidays and timezone.

next_occurrence

Find the next occurrence of a recurring pattern (daily, weekly, monthly, yearly).

format_time

Format a given time in relative, calendar, or custom formats within an optional timezone.

calculate_business_hours

Compute business hours between two times, with configurable hours, weekends, and holidays.

days_until

Calculate days until a target date or event and optionally format the result.