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 | 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