# 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)
```bash
npx mcp-chrono
```
### Global install
```bash
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):
```json
{
"mcpServers": {
"chrono": {
"command": "npx",
"args": ["-y", "mcp-chrono"]
}
}
}
```
### Claude Code
```bash
claude mcp add chrono -- npx -y mcp-chrono
```
Or with a custom data directory:
```bash
claude mcp add chrono -- npx -y mcp-chrono --data-dir /path/to/data
```
### Cursor
Add to `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"chrono": {
"command": "npx",
"args": ["-y", "mcp-chrono"]
}
}
}
```
### Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```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:
```json
{
"mcpServers": {
"chrono": {
"command": "npx",
"args": ["-y", "mcp-chrono"],
"transportType": "stdio"
}
}
}
```
With custom data directory:
```json
{
"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`:
```bash
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](https://timor.tech) (includes makeup workdays) |
| US | 10 federal holidays | [date.nager.at](https://date.nager.at) |
| HK | 17 public holidays (lunar, Easter, Ching Ming, fixed) | [date.nager.at](https://date.nager.at) |
## License
MIT
