How do I use mcp-chrono?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-chrono Convert 9 AM tomorrow in New York to Shanghai time and tell me the lunar date." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-chrono

by aleck31

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

mcp-chrono

MCP server providing time, calendar, timezone, Chinese lunar calendar, almanac, and date utilities for AI agents.

Quick Start

Using npx (no installation needed)

npx mcp-chrono

Global install

npm install -g mcp-chrono
mcp-chrono

Related MCP server: China Festival MCP Server

Usage with MCP Clients

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "chrono": {
      "command": "npx",
      "args": ["-y", "mcp-chrono"]
    }
  }
}

Claude Code

claude mcp add chrono -- npx -y mcp-chrono

Or with a custom data directory:

claude mcp add chrono -- npx -y mcp-chrono --data-dir /path/to/data

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "chrono": {
      "command": "npx",
      "args": ["-y", "mcp-chrono"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "chrono": {
      "command": "npx",
      "args": ["-y", "mcp-chrono"]
    }
  }
}

Generic MCP client (mcp.json)

Any MCP-compatible client can use the standard mcp.json format:

{
  "mcpServers": {
    "chrono": {
      "command": "npx",
      "args": ["-y", "mcp-chrono"],
      "transportType": "stdio"
    }
  }
}

With custom data directory:

{
  "mcpServers": {
    "chrono": {
      "command": "npx",
      "args": ["-y", "mcp-chrono", "--data-dir", "/path/to/data"],
      "transportType": "stdio"
    }
  }
}

Data Directory

Holiday API responses are cached locally to avoid repeated network requests. Default location: ~/.mcp-chrono/

Override with --data-dir:

npx mcp-chrono --data-dir /tmp/mcp-chrono-data

Tools

Time & Timezone

`get_current_time`

Get current time in any IANA timezone with detailed components (timestamp, weekday, week of year, day of year, UTC offset, etc.)

Parameter	Type	Required	Default	Description
`timezone`	string	No	`UTC`	IANA timezone (e.g. `Asia/Shanghai`, `America/New_York`)
`format`	string	No	`iso`	Output format: `iso`, `human`, or `relative`

`convert_timezone`

Convert a datetime between two IANA timezones.

Parameter	Type	Required	Description
`datetime`	string	Yes	ISO 8601 datetime (e.g. `2024-01-15T10:30:00`)
`from_timezone`	string	Yes	Source IANA timezone
`to_timezone`	string	Yes	Target IANA timezone

`list_timezones`

Search IANA timezones with current offsets and Chinese city names.

Parameter	Type	Required	Description
`query`	string	No	Search by timezone name, city, or Chinese name
`continent`	string	No	Filter by continent (e.g. `Asia`, `Europe`, `America`)

`parse_timestamp`

Parse Unix timestamps (seconds/milliseconds) or ISO 8601 strings into date components.

Parameter	Type	Required	Default	Description
`input`	string \| number	Yes	-	Unix timestamp (seconds or milliseconds) or ISO 8601 string
`timezone`	string	No	`UTC`	IANA timezone for output

Date Calculation

`calculate_time`

Add/subtract time from a date. Returns a new date after applying the offset.

Three modes: gregorian (standard date arithmetic), lunar (Chinese calendar arithmetic), anchor (offset from a named festival like 春节 or Thanksgiving).

Parameter	Type	Required	Default	Description
`mode`	string	No	`gregorian`	Calculation mode: `gregorian`, `lunar`, or `anchor`
`base_date`	string	No	now	Base date in ISO format. Defaults to current time if omitted
`timezone`	string	No	`UTC`	IANA timezone for the base date
`years`	integer	No	-	Years to add (negative to subtract)
`months`	integer	No	-	Months to add (negative to subtract)
`days`	integer	No	-	Days to add (negative to subtract)
`hours`	integer	No	-	Hours to add (negative to subtract)
`minutes`	integer	No	-	Minutes to add (negative to subtract)
`festival`	string	No	-	Festival name for `anchor` mode (e.g. `春节`, `Christmas`, `Thanksgiving`)
`festival_year`	integer	No	-	Year to resolve festival date for `anchor` mode

`date_diff`

Calculate the difference between two dates in years, months, days, hours, minutes, and total counts.

Parameter	Type	Required	Default	Description
`start`	string	Yes	-	Start date in ISO 8601 format
`end`	string	Yes	-	End date in ISO 8601 format
`timezone`	string	No	`UTC`	IANA timezone for parsing dates

`countdown`

Countdown from now to a target date with remaining days/hours/minutes/seconds.

Parameter	Type	Required	Default	Description
`target`	string	Yes	-	Target date/time in ISO 8601 format
`timezone`	string	No	`UTC`	IANA timezone for the target date

`calculate_business_days`

Count or add business days, skipping weekends and optionally public holidays (supports CN makeup workdays).

Parameter	Type	Required	Default	Description
`action`	string	Yes	-	`count` (count business days between two dates) or `add` (add business days to a date)
`from`	string	Yes	-	Start date in `YYYY-MM-DD` format
`to`	string	No	-	End date in `YYYY-MM-DD` format (required for `count`)
`business_days`	integer	No	-	Number of business days to add (required for `add`, negative to subtract)
`country`	string	No	-	Country code for public holidays (e.g. `CN`, `US`)
`timezone`	string	No	`UTC`	IANA timezone

Calendar & Festivals

`convert_calendar`

Convert between Gregorian and Chinese Lunar calendar. Returns Ganzhi (干支), zodiac, solar terms, festivals, constellation.

Parameter	Type	Required	Default	Description
`direction`	string	Yes	-	`gregorian_to_lunar` or `lunar_to_gregorian`
`year`	integer	Yes	-	Year
`month`	integer	Yes	-	Month (1–12)
`day`	integer	Yes	-	Day (1–31)
`isLeapMonth`	boolean	No	`false`	For `lunar_to_gregorian`: whether the month is a leap month (闰月)

`get_festivals`

List festivals, solar terms, and public holidays within a date range. Filterable by type.

Parameter	Type	Required	Default	Description
`start_date`	string	Yes	-	Start date in `YYYY-MM-DD` format
`end_date`	string	Yes	-	End date in `YYYY-MM-DD` format
`country`	string	No	`CN`	Country code for public holidays (e.g. `CN`, `US`, `HK`)
`types`	string[]	No	-	Filter by type: `lunar_festival`, `solar_festival`, `solar_term`, `public_holiday`

`get_month_info`

Month details: day count, first/last weekday, leap year, quarter, week count.

Parameter	Type	Required	Description
`year`	integer	Yes	Year (e.g. 2024)
`month`	integer	Yes	Month (1–12)

Chinese Almanac

`get_almanac`

Chinese almanac (黄历) for a date: 宜/忌 activities, lucky directions (喜神/财神/福神), conflict zodiac, 彭祖百忌, 吉神宜趋, 凶煞宜忌, 天神, 纳音, and more.

Parameter	Type	Required	Default	Description
`date`	string	No	today	Date in `YYYY-MM-DD` format

Persistent Countdowns

`manage_countdown`

CRUD for persistent countdown timers, stored as JSON on disk.

Parameter	Type	Required	Default	Description
`action`	string	Yes	-	`set`, `get`, `list`, or `delete`
`id`	string	No	-	Countdown ID (required for `get` / `delete`; auto-generated for `set` if omitted)
`name`	string	No	-	Name/description (required for `set`)
`target_date`	string	No	-	Target date in ISO 8601 format (required for `set`)
`timezone`	string	No	`UTC`	IANA timezone

Supported Regions

Region	Festivals	Public Holiday API
CN	27 festivals (lunar + solar)	timor.tech (includes makeup workdays)
US	10 federal holidays	date.nager.at
HK	17 public holidays (lunar, Easter, Ching Ming, fixed)	date.nager.at

License

MIT

Available Tools

13 tools

calculate_business_daysA

Calculate business days between two dates or add/subtract business days from a date. Skips weekends and optionally public holidays.

Inputs: action (required), from (required), to, business_days, +2 more.

calculate_timeB

Add or subtract time from a date. Supports Gregorian mode, Lunar mode, and anchor mode (calculate relative to a named festival).

Inputs: mode, base_date, timezone, years, +6 more.

convert_calendarA

Convert between Gregorian (solar) and Chinese Lunar calendar. Includes Ganzhi (天干地支), zodiac animal, solar terms, and festival information.

Inputs: direction (required), year (required), month (required), day (required), +1 more.

convert_timezoneB

Convert a datetime from one timezone to another. Input can be an ISO 8601 string.

Inputs: datetime (required), from_timezone (required), to_timezone (required).

countdownA

Calculate a countdown from now to a target date/time. Returns remaining days, hours, minutes, seconds and whether the date is in the past.

Inputs: target (required), timezone.

date_diffA

Calculate the difference between two dates/times. Returns the difference in years, months, days, hours, minutes and also total days/hours/minutes.

Inputs: start (required), end (required), timezone.

get_almanacA

Get Chinese almanac (黄历/老黄历) information for a specific date. Includes suitable activities (宜), things to avoid (忌), conflict zodiac (冲), lucky directions, and more.

Inputs: date.

get_current_timeA

Get the current time in a specified timezone. Returns detailed time information including year, month, day, hour, minute, second, weekday, week of year, day of year, and UTC offset.

Inputs: timezone, format.

get_festivalsA

Get festivals, solar terms, and public holidays within a date range. Supports Chinese (lunar and solar) festivals and public holidays from various countries.

Inputs: start_date (required), end_date (required), country, types.

get_month_infoA

Get detailed information about a specific month including number of days, first/last day weekday, whether it's a leap year, and quarter.

Inputs: year (required), month (required).

list_timezonesA

List IANA timezones with current offset and time. Uses the system's full IANA timezone database. Can filter by query text or continent.

Inputs: query, continent.

manage_countdownB

Manage persistent countdown timers. Supports CRUD operations: set (create), get (read one), list (read all), delete.

Inputs: action (required), id, name, target_date, +1 more.

parse_timestampB

Parse a Unix timestamp (seconds or milliseconds) or ISO 8601 string into detailed date/time components.

Inputs: input (required), timezone.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored 2026-04-18 06:15 across 13 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no significant overlap. For example, calculate_business_days focuses on business days, calculate_time on time arithmetic, convert_calendar on calendar conversion, and get_almanac on almanac data. The descriptions specify unique functionalities, making misselection unlikely.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case, such as calculate_business_days, convert_timezone, get_festivals, and manage_countdown. This predictability aids in understanding and usage without any deviations in style.

Tool Count5/5

With 13 tools, the count is well-scoped for a time and calendar utility server. Each tool serves a specific function, such as date calculations, conversions, and information retrieval, without redundancy or excessive bloat, fitting the domain appropriately.

Completeness5/5

The tool set provides comprehensive coverage for time and calendar operations, including calculations (e.g., date_diff, calculate_business_days), conversions (e.g., convert_calendar, convert_timezone), information retrieval (e.g., get_current_time, get_festivals), and management (e.g., manage_countdown). No obvious gaps are present for the stated purpose.

Resources

Related MCP Connectors

chrono-mcpA
io.github.nexus-api-lab
Deterministic time tools for AI agents: timezone conversion, business-day math, cron interpretation.
Developer Tools Calendar Management
2
https://chrono-mcp.dokasukadon.workers.dev/mcp
Epoch CalculatorA
com.epochcalc
Time and date math for AI agents: Unix timestamp conversion, DST-correct time zone conversion, durations, epoch arithmetic, cron schedules, and holiday countdowns. Eight tools, no key.
Calendar Management Developer Tools Workplace & Productivity
81
https://epochcalc.com/mcp
Chinese Astrology MCP Server by RoxyAPIA
com.roxyapi
BaZi four pillars, Chinese zodiac, lunisolar calendar and almanac days for AI agents.
Art & Culture
161
https://roxyapi.com/mcp/chinese-astrology
time-mcpA
io.github.jmavid
Current time, timezone conversion & date math for AI agents. On Cloudflare Workers.
Developer Tools
2
https://time-mcp.jmavid.workers.dev/mcp

Related MCP Servers

Chrono MCP
Developer Tools App Automation
JMoak
A
license
A
quality
C
maintenance
Provides comprehensive date, time, timezone, and calendar operations powered by Luxon, enabling AI agents to perform time calculations, timezone conversions, and temporal data handling across 400+ IANA timezones.
Updated 2 days ago (2026-11-08 21:28 UTC)
2
9 npm
MIT
China Festival MCP Server
Search
Eis4TY
A
license
Not graded
quality
C
maintenance
Provides Chinese holiday information, lunar calendar conversion, traditional festivals, 24 solar terms, and BaZi (Eight Characters) calculations for AI assistants to accurately handle Chinese calendar queries and date conversions.
Updated 3 months ago (2026-08-04 12:51 UTC)
3
Apache 2.0
Vreme Temporal MCP
Location Services Search
stefanveliki
A
license
A
quality
D
maintenance
Provides AI assistants with rich temporal intelligence including timezone conversions, 9 cultural calendars (Hebrew, Islamic, Chinese, etc.), astronomical events, Islamic prayer times, and context-aware activity appropriateness recommendations.
Updated a year ago (2025-11-30 06:04 UTC)
3
33 npm
MIT
Lunar Calendar MCP Server
Art & Culture Education & Learning Tools
NachaFromMars
A
license
Not graded
quality
C
maintenance
Enables Chinese traditional calendar functions including BaZi calculation, calendar conversion, Huangli query, daily fortune, solar terms, and Wu Xing analysis through natural language.
Updated 5 months ago (2026-06-23 06:24 UTC)
1
MIT

mcp-chrono

Quick Start

Using npx (no installation needed)

Global install

Usage with MCP Clients

Claude Desktop

Claude Code

Cursor

Windsurf

Generic MCP client (mcp.json)

Data Directory

Tools

Time & Timezone

get_current_time

convert_timezone

list_timezones

parse_timestamp

Date Calculation

calculate_time

date_diff

countdown

calculate_business_days

Calendar & Festivals

convert_calendar

get_festivals

get_month_info

Chinese Almanac

get_almanac

Persistent Countdowns

manage_countdown

Supported Regions

License

Available Tools

Tool Schema Changelog

TDQS

Resources

Related MCP Connectors

Related MCP Servers

Chrono MCP

China Festival MCP Server

Vreme Temporal MCP

Lunar Calendar MCP Server

`get_current_time`

`convert_timezone`

`list_timezones`

`parse_timestamp`

`calculate_time`

`date_diff`

`countdown`

`calculate_business_days`

`convert_calendar`

`get_festivals`

`get_month_info`

`get_almanac`

`manage_countdown`