Zmanim MCP Server
A comprehensive MCP server for calculating Jewish prayer times (zmanim).
A comprehensive Model Context Protocol (MCP) server for calculating Jewish prayer times (zmanim) using the python-zmanim library.
Overview
This MCP server provides tools to calculate various Jewish prayer times and astronomical times for any location worldwide. It uses the python-zmanim library, which is a Python port of the KosherJava project, implementing accurate astronomical calculations based on the NOAA algorithm.
Features
Available Tools
- zmanim_get_sunrise_sunset - Get sunrise and sunset times
- zmanim_get_shema_times - Get latest times for reciting the morning Shema (GR"A and MG"A opinions)
- zmanim_get_tefila_times - Get latest times for morning prayer/Shacharis (GR"A and MG"A opinions)
- zmanim_get_mincha_times - Get times for afternoon prayer including Mincha Gedola, Mincha Ketana, and Plag HaMincha
- zmanim_get_shabbat_times - Get Shabbat candle lighting and Havdalah times
- zmanim_get_daily_times - Get a comprehensive set of all daily zmanim
Key Features
- ✅ Support for multiple halachic opinions (GR"A, MG"A)
- ✅ Accurate NOAA-based astronomical calculations
- ✅ Support for any global location with latitude/longitude
- ✅ Timezone-aware calculations
- ✅ Optional date specification (defaults to today)
- ✅ Multiple output formats (Markdown and JSON)
- ✅ Customizable candle lighting offset
- ✅ Comprehensive error handling
Installation
Via PyPI (Recommended)
# For use with Claude Desktop or other MCP clients
uvx zmanim-mcp-server
Claude Desktop Configuration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"zmanim": {
"command": "uvx",
"args": ["zmanim-mcp-server"]
}
}
}
Usage Examples
Get Sunrise and Sunset
Get sunrise and sunset times for New York City today:
- Location: New York, NY
- Latitude: 40.7128
- Longitude: -74.0060
- Time Zone: America/New_York
Get Latest Shema Times
What time is the latest I can say Shema in Jerusalem?
- Location: Jerusalem
- Latitude: 31.7683
- Longitude: 35.2137
- Time Zone: Asia/Jerusalem
Get Shabbat Times
Get Shabbat candle lighting and Havdalah times for Chicago this Friday:
- Location: Chicago, IL
- Latitude: 41.8781
- Longitude: -87.6298
- Time Zone: America/Chicago
- Candle lighting offset: 18 minutes (can be customized)
Get Complete Daily Schedule
Give me all the prayer times for London today:
- Location: London
- Latitude: 51.5074
- Longitude: -0.1278
- Time Zone: Europe/London
Zmanim Explained
Morning Times
- Alos HaShachar (Dawn): First light, 72 minutes before sunrise
- Sunrise (Hanetz HaChama): When the sun rises above the horizon
- Sof Zman Krias Shema: Latest time to recite the morning Shema
- GR"A: 3 hours after sunrise
- MG"A: 3 temporal hours from dawn (typically earlier)
- Sof Zman Tefila: Latest time for morning prayer (Shacharis)
- GR"A: 4 hours after sunrise
- MG"A: 4 temporal hours from dawn (typically earlier)
Afternoon Times
- Chatzos: Solar noon, midpoint between sunrise and sunset
- Mincha Gedola: Earliest time for afternoon prayer (30 minutes after midday)
- Mincha Ketana: Preferred earliest time for Mincha (2.5 hours before sunset)
- Plag HaMincha: 1.25 hours before sunset (latest time according to some opinions)
Evening Times
- Sunset (Shkiah): When the sun sets below the horizon
- Tzeis HaKochavim: Nightfall, when stars appear (72 minutes after sunset)
Shabbat & Holidays
- Candle Lighting: Typically 18-40 minutes before sunset (varies by community)
- Havdalah: When Shabbat ends, typically at Tzeis (72 minutes after sunset)
Halachic Opinions
The server supports calculations according to different halachic authorities:
- GR"A (Vilna Gaon): Calculates day from sunrise to sunset
- MG"A (Magen Avraham): Calculates day from dawn (72 minutes before sunrise) to nightfall
Response Formats
Markdown Format (default)
Human-readable format with clear headers and organized sections, perfect for display.
JSON Format
Machine-readable structured data including ISO 8601 timestamps, suitable for programmatic use.
Input Parameters
All tools accept the following parameters:
- location (required): Name of the location (e.g., "New York, NY")
- latitude (required): Latitude in decimal degrees (-90 to 90)
- longitude (required): Longitude in decimal degrees (-180 to 180)
- time_zone (required): IANA timezone identifier (e.g., "America/New_York")
- date (optional): Date in YYYY-MM-DD format (defaults to today)
- response_format (optional): "markdown" or "json" (defaults to markdown)
For Shabbat times, there's an additional parameter:
- candle_lighting_offset (optional): Minutes before sunset (1-60, default 18)
Technical Details
Calculations
- Uses the NOAA (National Oceanic and Atmospheric Administration) algorithm
- Accounts for atmospheric refraction
- Timezone-aware using IANA timezone database
- Elevation can be incorporated in calculations
Dependencies
- fastmcp: Standalone FastMCP framework
- zmanim: Python port of KosherJava zmanim library
- pydantic: Input validation and data modeling
Common Location Examples
Troubleshooting
Server not appearing in MCP client
- Check that the path in your configuration is correct
- Ensure Python and all dependencies are installed
- Verify the configuration file syntax is valid JSON
- Restart your MCP client after configuration changes
Times showing as "N/A"
This typically occurs for locations near the poles where the sun doesn't rise or set on certain days. The calculations handle this gracefully by returning "N/A".
Timezone errors
Ensure you're using valid IANA timezone identifiers. You can find a list at: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
License
This MCP server uses the python-zmanim library, which is licensed under the GNU Lesser General Public License v2 or later (LGPLv2+), ported from the KosherJava project.
Credits
- Based on the python-zmanim library by pinnymz
- Original Java library: KosherJava by Eliyahu Hershfeld
- NOAA astronomical calculations
Support
For issues related to:
- This MCP server: Please open an issue with details about your configuration and the problem
- Zmanim calculations: Refer to the python-zmanim repository
- Halachic questions: Consult your local rabbi or posek
Future Enhancements
Potential additions to consider:
- Hebrew date calculations
- Fast day times
- Molad calculations
- Holiday determination
- Custom opinion configurations
- Multi-day range queries
- Export to calendar formats (iCal)
Note: This server is for informational purposes. For practical halachic decisions, please consult a qualified rabbi.