Rokuyo (六曜) is a traditional six-label calendar system used in Japan. You may see labels such as 大安 (Taian) and 友引 (Tomobiki) on calendars or when people discuss wedding dates.
We maintain Astromei, an astrology platform with a Japanese Rokuyo calendar. We extracted its calendar calculation into an open-source core library, then added a small Model Context Protocol adapter.
This tutorial shows how to run the source locally, query it from JavaScript, and connect its three read-only tools to a stdio MCP client.
The repositories are public, but the npm releases are still pending as of November 20, 2026. For now, use the source checkout rather than npx astromei.
You need Node.js 20 or later, npm, and Git:
git clone https://github.com/astromei/rokuyo-mcp.git
cd rokuyo-mcp
npm ci
npm run build
Installation needs network access. The MCP adapter currently depends on a pinned HTTPS Git commit of astromei-core; installation builds that dependency automatically. Calendar queries run locally afterward, without an API key or runtime network requests.
The initial supported date range is January 1, 2025 through December 31, 2027. This boundary is part of the API contract, not an invitation to extrapolate to other years.
Save the following as example.mjs in the checkout:
import {
getRokuyo,
getRokuyoMonth,
findRokuyoDates,
} from './dist/index.js';
const day = getRokuyo('2026-10-11');
console.log(day.rokuyo);
console.log(day.lunarDate);
const month = getRokuyoMonth(2026, 11);
console.log(month.length);
const taianDates = findRokuyoDates(
'2026-11-01',
'2026-11-30',
'大安',
);
console.log(taianDates.map(({ date }) => date));
Run it:
node example.mjs
These are the results from the current implementation:
先負
{ year: 2026, month: 9, day: 1, leap: false }
30
[
'2026-11-06',
'2026-11-10',
'2026-11-16',
'2026-11-22',
'2026-11-28'
]
The daily result also includes Japanese pronunciation, romaji, a short cultural description, and customary time-slot descriptions. Those descriptions explain calendar traditions; they are not forecasts.
Inputs use date-only strings in YYYY-MM-DD format, representing calendar dates in Asia/Tokyo. Invalid dates or dates outside the supported window throw RangeError. Range searches include both endpoints and accept at most 366 days.
The label calculation is small:
const labels = ['先勝', '友引', '先負', '仏滅', '大安', '赤口'];
const label = labels[(lunarMonth + lunarDay - 2) % 6];
The harder part is deciding which lunar month and day correspond to the input date. A one-day difference at a new-moon boundary changes the label.
For example, the current engine returns:
| Gregorian date | Lunar month/day | Rokuyo |
|---|---|---|
| 2026-10-10 | 8/30 | 先勝 |
| 2026-10-11 | 9/1 | 先負 |
Our lunar conversion uses the MIT-licensed korean-lunar-calendar, based on KASI's UTC+9 calendar. It follows the convention used by Astromei's calendar. It is not an official Japanese calendar, and Korean and Japanese calendar conventions should not be assumed identical for every historical or future year.
Substituting a UTC+8 lunar calendar can change the result near midnight new moons. That is why the library states its conversion source and restricts its supported window. A production integration should document its calendar convention just as explicitly as its timezone.
The adapter exposes three tools:
| Tool | Input | Purpose |
|---|---|---|
get_rokuyo |
date |
Return one date's Rokuyo and lunar date |
get_rokuyo_month |
year ,month |
Generate a Gregorian month's calendar |
find_rokuyo_dates |
start ,end , optionalrokuyo |
Find matching labels in a date range |
For a client supporting local stdio MCP servers, configure the built checkout:
{
"mcpServers": {
"astromei-rokuyo": {
"command": "node",
"args": ["/absolute/path/to/rokuyo-mcp/dist/stdio.js"]
}
}
}
Replace the path with your actual checkout path. If your desktop client does not inherit your shell's Node installation, use the full path to the Node executable too.
You can then ask the client: “List the Taian dates in November 2026.” The client can call find_rokuyo_dates and receive structured calendar results rather than inventing dates in prose.
All three tools are read-only. This first release does not calculate Japanese public holidays, Ichiryumanbaibi, Tenshanichi, astronomy, or birth charts. The npm-based launch configuration will become useful after the registry release; the source configuration above works independently of that release.
We separated the project into two layers:
The repository includes tests for date validation, bounded searches, the midnight new-moon boundary, and an actual MCP stdio handshake and tool invocation. Run them with npm test.
A model can help explain a returned label, but the date calculation stays in the deterministic layer. The same separation applies to cultural interpretation: describing a tradition should not turn it into a guarantee about an event's outcome.
The source is MIT licensed. If you would like to inspect the date behavior before integrating it, the browser calendar is another entry point.