CJK Calendar Converter MCP Server
This server converts historical East Asian dates between CJK lunisolar calendars, Julian Day Numbers, and Gregorian/Julian dates, and looks up era metadata.
Convert a CJK date string (e.g.
崇禎三年四月初三,M45.7.30) to a JDN, Gregorian/Julian dates, ganzhi, and all concurrent Chinese/Japanese/Korean/Vietnamese era equivalents viaconvert_cjk_date.Disambiguate reused era names with optional
country,dynasty, andemperorhints (e.g.北宋,肅宗,japanese).Convert a Julian Day Number to every calendar representation with
convert_jdn.Convert a Gregorian
YYYY-MM-DDdate back into JDNs and all concurrent CJK era dates withconvert_gregorian_date.Search era (年號) metadata by name, dynasty, or country — returning era name, dynasty, emperor, and date/JDN ranges — with
search_era.Surface ambiguity: results flag
ambiguous: truewithother_candidates, and note any hints that were ignored.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@CJK Calendar Converter MCP Server Convert 崇禎三年四月初三 to Gregorian"
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.
CJK Calendar Converter
A SQLite-backed historical calendar conversion system for Chinese, Japanese, Korean, and Vietnamese dates. Converts between traditional East Asian lunisolar calendars and the Gregorian/Julian calendar using Julian Day Numbers (JDN) as the universal pivot.
Designed for both human users (via REST API) and LLMs (via MCP server or API).
Disclaimer: This project has not been thoroughly tested against all historical sources. Calendar conversion for East Asian historical dates is inherently complex — different sources sometimes disagree on intercalary month placement, era boundaries, and calendar reform dates. There may be errors, especially for:
Dates during periods of dynastic transition or competing calendars
Vietnamese era year counts near era boundaries (±1 year offset possible)
Peripheral or short-lived dynasties not fully covered in the DILA dataset
Proleptic date ranges (hypothetical extensions before/after an era's actual use)
Always cross-reference with authoritative sources for scholarly or critical use.
How It Works
Every calendar date — whether Gregorian, Julian, Chinese lunisolar, Japanese imperial, Korean, or Vietnamese — can be mapped to a unique Julian Day Number (an integer counting days from January 1, 4713 BCE). This makes JDN the perfect intermediate representation:
崇禎三年四月初三 → JDN 2316539 → 1630-05-14 (Gregorian)
→ 寛永七年四月三日 (Japanese)
→ 天聰四年四月三日 (Later Jin/清前身)
→ 朝鮮七年四月三日 (Korean)
→ 後黎朝德隆元年四月三日 (Vietnamese)The database stores ~131,000 lunar month records with JDN ranges, covering:
Country | Coverage | Source |
China | ~220 BCE – 1912 CE | DILA Authority Database |
Japan | 593 – 1872 CE | DILA Authority Database |
Korea | 56 BCE – 1885 CE | DILA Authority Database |
Vietnam | ~544 – 1945 CE | Derived from Chinese lunar months + Vietnamese era data |
Related MCP server: shirabe-calendar-api
Quick Start
Prerequisites
uv (Python package manager)
Python 3.12+ (uv will install it automatically)
Setup
git clone https://github.com/kltng/calendar_converter.git
cd calendar_converter
# Install dependencies
uv sync --extra dev
# Download the DILA source data
mkdir -p data/raw
curl -L -o data/raw/authority_time.zip \
"https://authority.dila.edu.tw/downloads/authority_time.2012-02.zip"
cd data/raw && unzip authority_time.zip && cd ../..
# Build the SQLite database
uv run python -m data.scripts.build_db
uv run python -m data.scripts.add_vietnamese
uv run python -m data.scripts.apply_corrections
# Run tests to verify
uv run pytestRun the API Server
uv run uvicorn src.calendar_converter.api:app --reload --port 8000Open http://localhost:8000/docs for the interactive Swagger UI.
Docker
docker build -t calendar-converter .
docker compose upThe SQLite database is embedded in the container image — no external database needed.
Usage
1. REST API
Convert a CJK date
curl "http://localhost:8000/convert?date=崇禎三年四月初三"Response:
{
"jdn": 2316539,
"gregorian": "1630-05-14",
"julian": null,
"ganzhi": {
"year": "庚午",
"month": "辛巳",
"day": "壬子"
},
"cjk_dates": [
{
"era_name": "崇禎",
"dynasty_name": "明",
"country": "chinese",
"year_in_era": 3,
"month": 4,
"month_name": "四",
"is_leap_month": false,
"day": 3
},
{
"era_name": "天聰",
"dynasty_name": "後金",
"country": "chinese",
"year_in_era": 4,
"month": 4,
"day": 3
},
{
"era_name": "寛永",
"dynasty_name": "江戸時代",
"country": "japanese",
"year_in_era": 7,
"month": 4,
"day": 3
}
]
}Convert by Julian Day Number
curl "http://localhost:8000/convert?jdn=2316539"Convert by Gregorian date
curl "http://localhost:8000/convert?gregorian=1630-05-14"Disambiguate with country hint
When an era name is shared across countries, use the country parameter:
curl "http://localhost:8000/convert?date=天保三年閏九月十五日&country=japanese"Forgiving input
The hints are optional, and callers (language models above all) often guess them. So the lookup is forgiving:
countrymay be writtenchinese,China,中国,Japan,日本,Korea,Vietnamand so on, in any letter case.Era, dynasty and emperor names may be in simplified characters:
崇祯三年四月初三finds 崇禎.明朝finds 明.A hint that does not fit the date is dropped, and the answer says so in
notes:"notes": ["dynasty '崇禎' does not fit this date, so it was ignored"]. An era name used more than once is still reported withambiguous: trueandother_candidates.
Disambiguate era names
Many era names were reused across dynasties. When the converter finds multiple matching eras, the response includes ambiguous: true and an other_candidates list showing all alternative interpretations:
curl "http://localhost:8000/convert?date=乾德二年正月初一"{
"jdn": 2057111,
"gregorian": "0920-01-29",
"ambiguous": true,
"other_candidates": [
{
"jdn": 2073191,
"gregorian": "0964-02-21",
"era_name": "乾德",
"dynasty_name": "吳越",
"emperor_name": "忠懿王",
"country": "chinese",
"year_in_era": 2,
"month": 1,
"day": 1
},
{
"jdn": 2073191,
"gregorian": "0964-02-21",
"era_name": "乾德",
"dynasty_name": "北宋",
"emperor_name": "太祖",
"country": "chinese",
"year_in_era": 2,
"month": 1,
"day": 1
}
],
"cjk_dates": [ ... ]
}Use dynasty or emperor hints to narrow to a specific era:
# Narrow to Northern Song dynasty
curl "http://localhost:8000/convert?date=乾德二年正月初一&dynasty=北宋"
# Narrow by emperor name
curl "http://localhost:8000/convert?date=上元二年正月初一&emperor=肅宗"
# Combine hints
curl "http://localhost:8000/convert?date=至元三年正月初一&dynasty=元&emperor=順帝"When hints resolve the ambiguity, ambiguous will be false and other_candidates will be empty.
Search eras
# By era name
curl "http://localhost:8000/eras?name=崇禎"
# By dynasty
curl "http://localhost:8000/eras?dynasty=明"
# By country
curl "http://localhost:8000/eras?country=vietnamese"Batch convert
curl -X POST http://localhost:8000/convert/batch \
-H "Content-Type: application/json" \
-d '["崇禎三年四月初三", "康熙元年正月初一", "嘉隆元年正月初一"]'Download the database
curl -o calendar.db http://localhost:8000/db/download2. Use the SQLite Database Directly
Download calendar.db and query it with any SQLite client:
-- Find all eras named 崇禎
SELECT * FROM era_summary WHERE era_name = '崇禎';
-- Find the lunar month containing a specific JDN
SELECT m.*, es.era_name, es.dynasty_name, es.country
FROM month m
JOIN era_summary es ON es.era_id = m.era_id
WHERE m.first_jdn <= 2316539 AND m.last_jdn >= 2316539;
-- List all Vietnamese eras
SELECT era_name, dynasty_name, start_jdn, end_jdn
FROM era_summary WHERE country = 'vietnamese'
ORDER BY start_jdn;
-- Find concurrent eras for a given year (JDN range)
SELECT es.era_name, es.dynasty_name, es.country
FROM era_summary es
WHERE es.start_jdn <= 2316539 AND es.end_jdn >= 2316539;3. MCP Server (LLM Integration)
The MCP server lets LLMs call calendar conversion as a tool via the Model Context Protocol. Three transports are supported:
Option A: Streamable HTTP (Remote)
The deployed API includes an MCP endpoint at /mcp/. Use this with any MCP client that supports Streamable HTTP transport — no local installation needed.
{
"mcpServers": {
"calendar": {
"type": "streamable-http",
"url": "https://calendar-converter.098484.xyz/mcp/"
}
}
}Option B: SSE (Remote)
For MCP clients that use SSE transport (e.g., LM Studio), connect to the /sse/ endpoint:
{
"mcpServers": {
"calendar": {
"type": "sse",
"url": "https://calendar-converter.098484.xyz/sse/"
}
}
}Option C: stdio (Local)
For local use, run the stdio-based MCP server directly:
{
"mcpServers": {
"calendar": {
"command": "uv",
"args": ["run", "python", "-m", "src.calendar_converter.mcp_server"],
"cwd": "/absolute/path/to/calendar_converter"
}
}
}The stdio server also supports SSE transport for local use with clients like LM Studio:
uv run python -m src.calendar_converter.mcp_server --transport sse --port 8001Available MCP Tools
Tool | Description | Required Parameters |
| Convert a CJK date string to JDN + all equivalents |
|
| Convert a Julian Day Number to all calendars |
|
| Convert YYYY-MM-DD to all calendars |
|
| Search era metadata |
|
All conversion tools accept optional disambiguation parameters: country ("chinese", "japanese", "korean", "vietnamese"), dynasty (e.g., "唐", "北宋"), and emperor (e.g., "肅宗"). When an era name matches multiple eras, the response includes ambiguous: true with other_candidates listing all alternatives — the LLM can then re-query with hints.
Supported Input Formats
CJK Date Strings
Format | Example | Parsed As |
Standard Chinese |
| 崇禎 era, year 3, month 4, day 3 |
With 日 suffix |
| 康熙 era, year 61, month 12, day 29 |
Leap month (閏) |
| 天保 era, year 3, leap month 9, day 15 |
Yuan year (元年) |
| 崇禎 era, year 1, month 1, day 1 |
Zheng month (正月) |
| 嘉隆 era, year 1, month 1, day 1 |
廿/卅 shorthands |
| 康熙 era, year 3, month 12, day 29 |
Year only |
| First month of that year |
Year+month only |
| First day of that month |
Ganzhi year |
| 嘉慶 era, year with ganzhi 甲子 |
Full ganzhi |
| Resolved via sexagenary cycle lookup |
Mixed ganzhi+numeric |
| Ganzhi year + numeric month/day |
Numbered year + ganzhi day |
| 建元 era, year 6, month 6, the day 丁酉 (the usual form in the 正史) |
Ruler's name, no era name |
| The years stored as (無年號) or (王年) |
中 / 後 years of a Han emperor |
| The eras stored as (中元) and (後元) |
Japanese Shorthand
Format | Example | Parsed As |
Meiji |
| 明治45年7月30日 |
Taisho |
| 大正15年12月25日 |
Showa |
| 昭和64年1月7日 |
Heisei |
| 平成26年6月8日 |
Reiwa |
| 令和1年5月1日 |
Database Schema
dynasty (id, type) -- 'chinese'|'japanese'|'korean'|'vietnamese'
dynasty_name (dynasty_id, name, ranking, language_id)
└─ emperor (id, dynasty_id)
emperor_name (emperor_id, name, ranking, language_id)
└─ era (id, emperor_id)
era_name (era_id, name, ranking, language_id)
└─ month (id, era_id, year, month, month_name, leap_month,
first_jdn, last_jdn, ganzhi, start_from, status, eclipse)
era_summary (VIEW) -- denormalized join for queries: era + emperor + dynasty + JDN range
period -- historical period spans
day_comment -- annotations for specific JDNs (historical events, eclipses)The month table is the core: each row represents one lunar month with its JDN range. Individual days are derived from first_jdn + (day - start_from).
Corrections to the DILA data
data/scripts/apply_corrections.py fixes known errors after the build, and records each fix in the table data_correction (key, description, applied_at). It is safe to run more than once.
Key | Correction |
| The era of 西漢 成帝 that starts in 32 BCE is 建始 (漢書 卷10), not 始建. |
| 中宗 of Joseon counts from his accession year, 1506, as in the Sillok (中宗 1년 9월 2일). 燕山君 ends on 12年 9月 1日. |
| 仁祖 of Joseon counts from his accession year, 1623, as in the Sillok (仁祖 1년 3월 13일). 光海君 ends on 15年 3月 12日. So 1644-04-25 is 仁祖 22年 3月 19日. |
Both kings took the throne after the king before them was deposed. The Sillok counts that year as year 1; the DILA data started the count one year later. For other Joseon kings the data already agrees with the Sillok.
Key Concepts
Julian Day Number (JDN): A continuous integer day count starting from noon GMT, January 1, 4713 BCE (Julian calendar). Every calendar date maps to exactly one JDN. This avoids needing pairwise conversion formulas between calendar systems.
Lunisolar Calendar: East Asian calendars track both lunar months (29–30 days) and solar years. When a lunar month contains no "major solar term" (中氣), it becomes an intercalary/leap month (閏月). This is determined astronomically, not by formula — historical data must be looked up.
Era Names (年號): Reign-period names that reset year counting. One emperor could use multiple era names. The same name can appear in different dynasties and countries (e.g., 太平 was used 10+ times). Always use dynasty or country for disambiguation.
Sexagenary Cycle (干支): A 60-unit cycle from 10 Heavenly Stems (天干) × 12 Earthly Branches (地支). Applied to years, months, days, and hours. Year ganzhi is stored in the database; month ganzhi is computed via the 五虎遁 formula; day ganzhi is computed from JDN.
Proleptic Dates: Dates marked status='P' extend a calendar system beyond its actual historical use (e.g., using an era name for dates after that era ended, because historical sources reference them that way).
Agent Skill (Claude Code / LLM Tool Use)
The skill/ directory contains a standalone agent skill — a self-contained, zero-dependency Python script with its own SQLite database that any LLM agent (Claude Code, etc.) can use for calendar conversion without needing the full API server.
What's Included
skill/
├── SKILL.md # Skill manifest and documentation
├── scripts/
│ ├── calendar_converter.py # Standalone converter (Python 3.10+, stdlib only)
│ └── .gitignore # Ignores downloaded calendar.db
├── references/
│ └── database_schema.md # SQLite schema and query patterns
└── tests/
└── test_calendar_converter.py # Offline tests: cd skill && python3 -m unittest discover -s testsThis folder is a copy of the cjk-calendar skill published in kltng/humanities-skills (version 1.0.3). Make changes there first, then copy them here.
Setup
# Download the SQLite database (~14 MB) on first use
python3 skill/scripts/calendar_converter.py setupCLI Usage
# CJK date → Gregorian
python3 skill/scripts/calendar_converter.py convert "崇禎三年四月初三"
# Gregorian → all CJK calendars
python3 skill/scripts/calendar_converter.py gregorian 1644 4 25
# Julian Day Number → all calendars
python3 skill/scripts/calendar_converter.py jdn 2299161
# Search eras
python3 skill/scripts/calendar_converter.py eras --name 康熙
python3 skill/scripts/calendar_converter.py eras --dynasty 明 --country chineseAdding to a Skill Hub
Copy the skill/ directory (or symlink it) into your skill hub:
cp -r skill/ /path/to/your-skill-hub/cjk-calendarThe skill is fully self-contained: zero external dependencies, downloads its own database, and runs with Python 3.10+ stdlib only.
Development
# Run all tests (1416 tests)
uv run pytest
# Run a single test file
uv run pytest tests/test_parser.py
# Run a specific test
uv run pytest tests/test_converter.py::TestGanzhi::test_full_ganzhi_in_conversion -v
# Run CBDB verification tests only
uv run pytest tests/test_cbdb_verification.py -v
# Rebuild the database from scratch
uv run python -m data.scripts.build_db
uv run python -m data.scripts.add_vietnamese
uv run python -m data.scripts.apply_correctionsTest Suites
File | Tests | Description |
| 23 | CJK date string parsing |
| 39 | JDN conversion, ganzhi, disambiguation |
| 19 | FastAPI endpoint integration |
| 10 | MCP stdio server tools |
| 5 | DILA reference date verification |
| 1310 | Era name cross-validation against external dataset |
Data Sources and Acknowledgements
This project builds on the work of several institutions and individuals:
DILA Authority Database (Primary Source)
The core calendar data (Chinese, Japanese, Korean) comes from the Dharma Drum Institute of Liberal Arts (DILA) Time Authority Database, assembled between 2008–2010 by the Library and Information Center of Dharma Drum Buddhist College (法鼓佛教學院).
Website: https://authority.dila.edu.tw/
Download: https://authority.dila.edu.tw/docs/open_content/download.php
Author: Simon Wiles, DDBC
License: Creative Commons Attribution-ShareAlike 3.0 Unported
Japanese data builds upon data provided by Takashi SUGA
The DILA database uses Julian Day Numbers as the fundamental unit for date designation, with lunar months as the smallest stored entity. This elegant design inspired the architecture of this project.
CeJS (Colorless echo JavaScript)
The CeJS library by kanasimi provided reference data for Vietnamese calendar eras and validation of conversion results.
Repository: https://github.com/kanasimi/CeJS
Era Converter Demo: https://kanasimi.github.io/CeJS/_test%20suite/era.htm
Coverage: 246 BCE – 2100 CE across multiple calendar systems
CBDB (China Biographical Database)
The CBDB project at Harvard University provided nianhao (era name) verification data used for cross-validation testing.
Website: https://projects.iq.harvard.edu/cbdb
NIAN_HAO table: https://input.cbdb.fas.harvard.edu/codes/NIAN_HAO
Related NPM package (cn-era): https://www.npmjs.com/package/cn-era
Julian Day Number Algorithms
JDN ↔ Gregorian/Julian conversion algorithms are based on:
Jean Meeus, Astronomical Algorithms (Willmann-Bell, 1991)
E.G. Richards, "Calendars" in Explanatory Supplement to the Astronomical Almanac (2013)
Vietnamese Historical Data
Vietnamese dynasty and era information is derived from:
Đại Việt sử ký toàn thư (大越史記全書) — Complete Annals of Đại Việt
CeJS Vietnamese era data (see above)
Sexagenary Cycle (干支) Computation
Month ganzhi uses the traditional 五虎遁 (Five Tigers) formula. Day ganzhi is computed from JDN using a mod-60 cycle calibrated against known historical dates.
License
The DILA Authority Database data is licensed under CC BY-SA 3.0. The code in this repository is available under the MIT License. If you use the calendar data, please attribute the DILA Authority Database as required by their license.
Browser MCP clients
For browser or Chrome extension clients, set MCP_ALLOWED_ORIGINS to a
comma-separated list of exact origins, for example
chrome-extension://<extension-id>,https://your-client.example. Whitespace and
empty entries are ignored. Keep MCP_ALLOWED_HOST set to the server hostname.
Restart the service after changing these variables. An empty origin list rejects
requests with an Origin header; clients without one continue to work.
Available Tools
4 toolsconvert_cjk_dateA
Convert a CJK (Chinese/Japanese/Korean/Vietnamese) historical date to Julian Day Number and equivalent dates in all concurrent calendars.
Input examples: '崇禎三年四月初三', '康熙元年正月初一', '寛永七年四月初三', 'M45.7.30'. Returns JDN, Gregorian date, Julian date (pre-1582), ganzhi (干支), and all concurrent CJK era representations.
Args: date: CJK date string, e.g. '崇禎三年四月初三' or 'M45.7.30' country: Optional country hint to disambiguate era names (chinese, japanese, korean, vietnamese) dynasty: Optional dynasty hint to disambiguate era names, e.g. '唐', '元', '北宋' emperor: Optional emperor hint to disambiguate era names, e.g. '肅宗', '順帝'
Inputs: date (required), country, dynasty, emperor. Returns: result
convert_gregorian_dateA
Convert a Gregorian date (YYYY-MM-DD) to Julian Day Number and all concurrent CJK era dates.
Args: date: Gregorian date in YYYY-MM-DD format
Inputs: date (required). Returns: result
convert_jdnA
Convert a Julian Day Number to all calendar representations.
Returns Gregorian, Julian, ganzhi (干支), and all concurrent CJK era dates.
Args: jdn: Julian Day Number
Inputs: jdn (required). Returns: result
search_eraA
Search for era (年號) metadata by name, dynasty, or country.
Returns era name, dynasty, emperor, date range, and JDN range.
Args: name: Era name, e.g. '崇禎', '康熙', '寛永' dynasty: Dynasty name, e.g. '明', '清', '唐' country: Filter by country (chinese, japanese, korean, vietnamese)
Inputs: name, country, dynasty. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: converting from a CJK date, from a Julian Day Number, from a Gregorian date, and searching era metadata. There is no overlap or ambiguity between them.
All tools follow a consistent verb_noun pattern: convert_cjk_date, convert_jdn, convert_gregorian_date, and search_era. The naming convention is uniform and predictable.
Four tools is an appropriate, minimal set for a calendar converter server. Each tool covers a necessary conversion direction or lookup, and none are redundant or missing.
The server covers all major conversion paths: from CJK, JDN, and Gregorian dates, plus era searching. It returns all relevant calendar representations (Gregorian, Julian, ganzhi, CJK eras), so the surface is complete for its domain.
Maintenance
Related MCP Connectors
MCP server for China public holidays and lunar calendar: solar-lunar conversion and yearly schedule.
Deterministic calendars and cosmic date JSON for AI agents via MCP (Gregorian 1900-2100).
Hosted remote MCP server for BaZi (Four Pillars) charts and the Chinese almanac. No install.
BaZi four pillars, Chinese zodiac, lunisolar calendar and almanac days for AI agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides professional Chinese astrology calculations including Four Pillars, Five Elements, zodiac signs, and lunar calendar details. It allows users to perform accurate Bazi analysis with global timezone support directly within MCP-compatible clients.18 npm10MIT
- AlicenseNot gradedqualityDmaintenanceJapanese calendar API for AI agents. Provides Rokuyo, Rekichu, Eto, 24 Solar Terms, and fortune judgments. MCP + REST API.MIT
- FlicenseNot gradedqualityDmaintenanceEnables Korean lunar-solar birthday conversion, including leap month support, using a Streamable HTTP MCP server.-
- AlicenseAqualityDmaintenanceProvides MCP tools for Chinese metaphysics, including BaZi (Four Pillars) charting, Liu Yao hexagram casting, lunar conversion, and AI-powered destiny analysis.1034 npmMIT