MCP Ukrainian Calendar: Building an Open-Source MCP Server

There's something satisfying about a small project that works exactly as intended. The MCP Ukrainian Calendar server started as a practical need — AI assistants know almost nothing about Ukrainian traditional holidays, pagan seasonal celebrations, or the folk calendar that shaped Ukrainian culture for centuries — and turned into a clean illustration of how to build and publish an MCP server from scratch.

The server is live on GitHub at https://github.com/ChuprinaDaria/mcp-ukrainian-calendar and listed on mcpservers.org at https://mcpservers.org/servers/chuprinadaria/mcp-ukrainian-calendar.

The Problem: AI Doesn't Know Ukrainian Traditions

Ask any major AI assistant about Ukrainian holidays and you get a combination of Orthodox Christian holidays (which are well-documented online) and, if you're lucky, a few modern civic holidays. What you won't get is:

• Kupala Night (Ivan Kupala) and its pagan fire and water rituals
• Malanka, the old New Year celebration with its costumed processions
• Kolodiy, the pre-Lent festivities tied to the feminine principle
• The full cycle of seasonal agricultural rites documented by ethnographers like Valeriy Voytovych

Voytovych's encyclopedic work on Ukrainian mythology and folk calendar is a remarkable resource. The Ukrainian traditional calendar is layered — pre-Christian Slavic rites syncretized with Orthodox Christianity, agricultural seasons with their corresponding rituals, each month with its characteristic observances. This is not trivia. It's living culture that many Ukrainians actively practice or want to understand.

Standard AI training data skews heavily toward English-language internet content. Ukrainian cultural heritage — especially pre-Christian folk traditions — is underrepresented. An MCP server is a practical way to bridge that gap for anyone using MCP-compatible AI tools.

What MCP Is (for the Uninitiated)

Model Context Protocol is Anthropic's open standard for connecting AI models to external tools and data sources. An MCP server is a process that exposes capabilities — tools, resources, prompts — that any MCP-compatible AI client can discover and use.

The key insight: you don't need to fine-tune a model or modify any AI system to add new capabilities. You write an MCP server, connect it to your AI client, and the capabilities are immediately available.

Think of it as a plugin system for AI, but standardized across clients and models.

Architecture of the Server

The Ukrainian Calendar MCP server is intentionally simple. Simplicity here is a feature — an MCP server that's hard to understand is hard to trust and hard to maintain.

The server exposes three tools:

get_holiday_by_date — Given a date (or month/day), returns all Ukrainian traditional observances for that date: the holiday name, its traditional customs, symbolic meaning, and any associated folk rituals.

get_holidays_by_month — Returns the full calendar of observances for a given month. Useful when an AI assistant is helping plan events or explaining seasonal themes.

search_holidays — Full-text search across the holiday database by keyword. Want to find all celebrations involving water? Fire? Specific agricultural activities? This is how you find them.

The data layer is a structured JSON dataset compiled from ethnographic sources, primarily Voytovych's work on the folk calendar. Each entry includes:

{
  "date": "07-07",
  "name": "Ivan Kupala (Kupala Night)",
  "traditional_name": "Іван Купала",
  "type": "folk_pagan_syncretized",
  "customs": [
    "Jumping over bonfires for purification and health",
    "Weaving flower crowns and floating them on rivers",
    "Searching for the mythical fern flower at midnight",
    "Ritual bathing in rivers and dew"
  ],
  "symbolism": "Summer solstice celebration; water and fire purification; fertility and love divination",
  "source": "Voytovych folk calendar tradition"
}

Building the MCP Server: Step by Step

The server uses the official MCP Python SDK (mcp). The structure is straightforward:

1. Install dependencies

pip install mcp
# or with uv (recommended)
uv add mcp

2. Define the server and its tools

from mcp.server import Server
from mcp.server.models import InitializationOptions
from mcp.types import Tool, TextContent
import mcp.server.stdio as stdio

server = Server("ukrainian-calendar")

@server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="get_holiday_by_date",
            description=(
                "Get Ukrainian traditional holidays and observances for a specific date. "
                "Returns folk customs, pagan traditions, and cultural significance. "
                "Date format: MM-DD (e.g., '07-07' for July 7th)."
            ),
            inputSchema={
                "type": "object",
                "properties": {
                    "date": {
                        "type": "string",
                        "description": "Date in MM-DD format",
                        "pattern": "^\\d{2}-\\d{2}$"
                    }
                },
                "required": ["date"]
            }
        ),
        # ... other tools
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]:
    if name == "get_holiday_by_date":
        date = arguments["date"]
        holidays = calendar_data.get(date, [])

        if not holidays:
            return [TextContent(
                type="text",
                text=f"No specific traditional observances recorded for {date}."
            )]

        result = format_holidays(holidays)
        return [TextContent(type="text", text=result)]

    raise ValueError(f"Unknown tool: {name}")

3. The entry point

async def main():
    async with stdio.stdio_server() as (read_stream, write_stream):
        await server.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="ukrainian-calendar",
                server_version="0.1.0",
            )
        )

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

4. Make it installable

The pyproject.toml entry point is what allows installation via uvx:

[project.scripts]
mcp-ukrainian-calendar = "mcp_ukrainian_calendar.server:main_sync"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

Publishing to mcpservers.org

mcpservers.org is the community directory for MCP servers. Getting listed involves:

1. Publishing the package to PyPI (so it's installable via uvx or pip)
2. Submitting a PR to the mcpservers.org repository with your server's metadata
3. The metadata includes: name, description, tools list, installation instructions, license

The listing format is standardized. Your server needs a working README.md that explains what it does, how to install it, and how to configure it in Claude Desktop or other MCP clients. The community reviews and merges.

For Claude Desktop users, the configuration is simply:

{
  "mcpServers": {
    "ukrainian-calendar": {
      "command": "uvx",
      "args": ["mcp-ukrainian-calendar"]
    }
  }
}

After that, Claude can answer questions about Ukrainian folk holidays with actual depth — Kupala Night rituals, the meaning of Maslyana, which dates carry specific agricultural significance in the traditional calendar.

What This Demonstrates

The Ukrainian Calendar server is small on purpose. It demonstrates something important: MCP lowers the barrier for adding specialized knowledge to AI systems to the point where domain experts — historians, ethnographers, practitioners of a craft — can package their knowledge and make it available to AI users without waiting for a major lab to add it to training data.

The folk traditions documented by Voytovych took decades of fieldwork to compile. That knowledge can now be available to any AI assistant, immediately, through an MCP server that took a weekend to build.

That's the actual promise of the protocol: not just connecting AI to databases and APIs, but making specialized human knowledge accessible to AI in a standardized, composable way.

The server is open source and welcomes contributions — especially for expanding the holiday dataset and adding regional variations. Find it at github.com/ChuprinaDaria/mcp-ukrainian-calendar.