liturgical-calendar

The Liturgical Calendar MCP Server provides a secure, programmatic interface to access the Roman Catholic Liturgical Calendar data for any year, including general, national, and diocesan calendars. It exposes tools for listing available calendars, retrieving the general calendar for a year, obtaining national and diocesan calendars, and pulling liturgy information for specific dates. You can also fetch the Easter announcements and moveable feasts (Noveritis) for a given year and calendar. The server automatically flags particular celebrations that are unique to a calendar, helping you distinguish universal liturgies from regional observances. Use this in AI assistants to reason about liturgical dates, saints, and feast particulars in a localized context.

To use, start the Liturgical Calendar MCP tool via your MCP client (e.g., Claude Desktop or LangChain-enabled runtimes) by invoking the litcal tool. Then call tools such as get_general_calendar(year, locale), get_national_calendar(country_code, year), get_diocesan_calendar(diocese_id, year), list_available_calendars(), get_liturgy_of_the_day(date, calendar), and get_announcement_easter_and_moveable_feasts(year, calendar). The responses return structured data including date-specific celebrations, locale details, and indicators for particular celebrations when relevant. This enables applications to reason about liturgical contexts and plan events or messaging around feast days with regional specificity.

Prerequisites:

• Docker Desktop installed with MCP Toolkit support (or equivalent container runtime capable of running MCP servers)
• No authentication required for the public Liturgical Calendar API access

Installation steps:

1. Clone the repository (or prepare your Docker image as described in the project notes):

git clone https://github.com/CatholicOS/liturgical-calendar-mcp.git
cd liturgical-calendar-mcp

2. Build the Docker image for the MCP server:

docker build -t litcal-mcp-server .

3. Run the MCP server image directly (for testing):

docker run -it litcal-mcp-server

4. Integrate with Docker MCP Toolkit (recommended for tooling integration):
   • Edit the MCP catalog to add a new entry for the Liturgical Calendar server (as described in the project wiki and README):

  litcal:
    description: "Access Roman Catholic Liturgical Calendar data for any year, nation, or diocese from 1970-9999"
    title: "Liturgical Calendar"
    type: server
    dateAdded: "2025-10-22T00:00:00Z"
    image: litcal-mcp-server:latest
    ref: ""
    readme: ""
    toolsUrl: ""
    source: ""
    upstream: ""
    icon: ""
    tools:
      - name: get_general_calendar
      - name: get_national_calendar
      - name: get_diocesan_calendar
      - name: list_available_calendars
      - name: get_liturgy_of_the_day
      - name: get_announcement_easter_and_moveable_feasts
    metadata:
      category: integration
      tags:
        - catholic
        - liturgy
        - calendar
        - religious
      license: MIT
      owner: local

• Also update the registry to reference the new server:

  litcal:
    ref: ""

5. Run tests by invoking a tool call from your MCP client (e.g., using the litcal get_general_calendar tool) to verify connectivity and responses.

Notes:

• Docker MCP Toolkit may reset custom catalog/registry entries on restart; you may need to re-apply the catalog/registry edits as described above.
• The API is publicly accessible and does not require authentication in the described setup.

Tips and common considerations:\n- The server supports queries for the General Roman Calendar, national calendars, and diocesan calendars with historical data from 1970 to 9999.\n- When retrieving calendars for nations or dioceses, the server marks particular celebrations and excludes minor weekday events (grade 0) to highlight regional differences.\n- If you customize using litcal.config.yaml, you can adjust API endpoints, caching behavior, and timeouts via the provided configuration options (see the README for details).\n- If you run into issues where tool calls stop working after a restart, you may need to reapply entries in the Docker MCP catalogs/registry as described in the README.\n- No authentication is required to access the public Liturgical Calendar API through this MCP server.