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
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 |
Tools 6
get_current_timeGet current time in any IANA timezone with detailed components.convert_timezoneConvert a datetime between two IANA timezones.list_timezonesSearch IANA timezones with current offsets and Chinese city names.parse_timestampParse Unix timestamps or ISO 8601 strings into date components.calculate_timeAdd or subtract time from a date using gregorian, lunar, or anchor modes.date_diffCalculate the difference between two dates in various units.