```
╔══════════════════════════════════════════════════════════════╗
║  ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦  ║
║  · ◆ ·       U K R A I N I A N   C A L E N D A R       · ◆ · ║
║  ✦ · ✦ ·           M C P   S E R V E R             · ✦ · ✦  ║
║  · ◆ · ◆ ·   ─────────────────────────────────   · ◆ · ◆ ·  ║
║  ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦ · ✦  ║
╚══════════════════════════════════════════════════════════════╝
```

<div align="center">

[![npm version](https://img.shields.io/npm/v/mcp-ukrainian-calendar?style=flat-square&color=B22222)](https://www.npmjs.com/package/mcp-ukrainian-calendar)
[![License: MIT](https://img.shields.io/badge/license-MIT-C8A832?style=flat-square)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18-3B6B3B?style=flat-square)](https://nodejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-2C5F7C?style=flat-square)](https://www.typescriptlang.org)
[![MCP](https://img.shields.io/badge/MCP-compatible-1A1A2E?style=flat-square)](https://modelcontextprotocol.io)

**Ukrainian pagan calendar as an MCP server — holidays, deities, folk wisdom, and birth charms.**

*Сервер MCP з українським язичницьким календарем — свята, боги, народна мудрість, обереги.*

</div>

---

## Features

| | |
|---|---|
| 🗓 **120 pagan holidays** | Full calendar with traditions, rituals, and preparation guides |
| ⚡ **184 deities** | Ukrainian/Slavic pantheon from the Voytovych encyclopedia |
| 🌾 **365 folk wisdoms** | Daily weather proverbs and agricultural sayings |
| 🔮 **8 birth charm periods** | Personal patron deity based on your birthday |
| 🇺🇦 **Ukrainian language** | All content in Ukrainian — authentic and unabridged |
| 📦 **Zero extra dependencies** | Only the MCP SDK. No bloat. |

---

## Quick Start

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "ukrainian-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-ukrainian-calendar"]
    }
  }
}
```

### Claude Code (CLI)

```bash
claude mcp add ukrainian-calendar -- npx -y mcp-ukrainian-calendar
```

### Cursor

Add to your Cursor MCP settings (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "ukrainian-calendar": {
      "command": "npx",
      "args": ["-y", "mcp-ukrainian-calendar"]
    }
  }
}
```

---

## Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `get_today_holiday` | Holidays for today or a specific date, with traditions and rituals | `date?` — DD.MM format |
| `get_upcoming_holidays` | List of upcoming holidays in the next N days | `days?` — 1–365 (default 7) |
| `get_holiday_details` | Full details for a holiday by name or slug | `query` — name or slug |
| `search_holidays` | Search holidays by keyword across name, description, traditions | `query` — search text |
| `get_season_holidays` | All holidays for a given season | `season` — winter/spring/summer/autumn |
| `get_deity` | Info about a deity or mythological figure | `query` — name or slug |
| `search_deities` | Search deities by name or filter by group | `query?`, `group?` |
| `get_folk_wisdom` | Daily folk proverb for today or a specific date | `date?` — DD.MM format |
| `get_charm` | Personal birth charm with patron deity and ornament | `birthday` — DD.MM format |

**Deity groups:** `supreme` · `warrior` · `fertility` · `underworld` · `nature` · `household`

---

## Example Prompts

### Holidays & Calendar

```
What Ukrainian pagan holidays are coming up this week?
```
```
Tell me about Купало — traditions, rituals, how to prepare.
```
```
What holidays are celebrated in Ukrainian paganism during winter?
```
```
Search for holidays related to fire in Ukrainian tradition.
```

### Deities & Mythology

```
Who is Перун? Tell me about this deity.
```
```
List all deities of the underworld in Ukrainian mythology.
```
```
Who are the household deities in Slavic tradition?
```

### Folk Wisdom & Charms

```
What does Ukrainian folk wisdom say about today's weather?
```
```
What is the folk proverb for March 25th?
```
```
I was born on 15.08 — what is my birth charm and patron deity?
```

---

## Data Sources

All content is based on **Valerii Voytovych's encyclopedic work on Ukrainian mythology**, supplemented by traditional folk calendar materials. The deity database contains 184 figures from the Ukrainian/Slavic pantheon with descriptions faithful to the source.

> Войтович В. *Українська міфологія* — the authoritative reference for Ukrainian pre-Christian beliefs, deities, and ritual tradition.

---

## License

MIT — use freely, attribute kindly.

---

<div align="center">

*Built for the curious, the rootseekers, and those who wonder what their ancestors celebrated.*

◆ · ✦ · ◆ · ✦ · ◆ · ✦ · ◆ · ✦ · ◆

👾 Created by [Daria Chuprina](https://www.threads.com/@sonya_orehovaya) · just because she can!

[Threads](https://www.threads.com/@sonya_orehovaya) · [LinkedIn](https://www.linkedin.com/in/dchuprina/) · [Lazysoft](https://lazysoft.pl) · info@lazysoft.pl

© 2026 Lazysoft · Wrocław, Polska

</div>