# Hebcal MCP Server
An MCP server that provides access to Shabbat times and Jewish holidays using the Hebcal API.
## Description
This server allows you to get up-to-date and accurate information about:
- Shabbat candle lighting and Havdalah times for various cities in Israel
- The next upcoming Jewish holiday
- All upcoming holidays and Shabbat times
## Prerequisites
Install dependencies using uv:
```bash
uv add fastmcp requests
```
## Installation and Setup in Claude Desktop
### Step 1: Save the File
Save the code in a file named `hebcal_server.py` in a convenient location on your computer.
### Step 2: Configure Claude Desktop
Open the Claude Desktop configuration file:
**On macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
**On Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```
### Step 3: Add Server Configuration
Add the following configuration to the config file:
```json
{
"mcpServers": {
"project": {
"command": "uv",
"args": [
"--directory",
"/path/to/hebcal-mcp.py",
"run",
"main.py"]
}
}
}
```
**Note:** Replace `/path/to/hebcal-mcp.py` with the full path to your file.
For example:
- macOS: `"/Users/username/mcp-servers/hebcal-mcp"`
- Windows: `"C:\\Users\\username\\mcp-servers\\hebcal-mcp"`
### Step 4: Restart
Close and restart Claude Desktop for the changes to take effect.
## Available Tools
### 1. `get_shabbat_times`
Returns candle lighting and Havdalah times for the upcoming Shabbat in a specific Israeli city.
**Input:**
- `city` (str): City name in English
**Supported Cities:**
- jerusalem
- tel aviv
- haifa
- beer sheva
- ashdod
- eilat
**Output:**
A list with two items:
```
["2025-11-14 Candle lighting: 16:24", "2025-11-15 Havdalah: 17:20"]
```
**Usage Examples:**
- "When is Shabbat in Ashdod?"
- "Show me Shabbat times in Jerusalem"
- "What time does Shabbat end in Tel Aviv?"
**Example Response:**
```
Shabbat candle lighting in Ashdod is on Friday, November 14, 2025 at 16:24.
Havdalah (Shabbat end) will be on Saturday, November 15 at 17:20.
Shabbat Shalom!
```
---
### 2. `get_all_shabbat_times`
Returns all Shabbat candle lighting and Havdalah times until the end of the year.
**Input:** No parameters
**Output:**
A list of all upcoming Shabbat times:
```
[
"2025-11-14 Candle lighting: 16:22",
"2025-11-15 Havdalah: 17:34",
"2025-11-21 Candle lighting: 16:20",
...
]
```
**Usage Examples:**
- "Show me all upcoming Shabbat times"
- "When are all Shabbats until the end of the year?"
**Example Response:**
```
Here are all the upcoming Shabbat times until the end of the year:
November 2025:
- Friday, November 14 at 16:22 → Saturday, November 15 at 17:34
- Friday, November 21 at 16:20 → Saturday, November 22 at 17:33
- Friday, November 28 at 16:19 → Saturday, November 29 at 17:32
December 2025:
- Friday, December 5 at 16:18 → Saturday, December 6 at 17:32
...
```
---
### 3. `get_the_next_holiday`
Returns the next upcoming Jewish holiday.
**Input:** No parameters
**Output:**
A list with one holiday:
```
["2025-11-20 Sigd"]
```
**Usage Examples:**
- "When is the next holiday?"
- "What holiday is coming up?"
- "What's the next Jewish holiday?"
**Example Response:**
```
The next holiday is Sigd on Thursday, November 20, 2025.
Sigd is a holiday celebrated by Ethiopian Jews, marking the yearning for Jerusalem
and the Land of Israel, observed 50 days after Yom Kippur.
```
---
### 4. `get_all_holiday_times`
Returns all Jewish holidays until the end of the year.
**Input:** No parameters
**Output:**
A list of all holidays:
```
[
"2025-11-20 Sigd",
"2025-11-26 Ben-Gurion Day",
"2025-12-14 Chanukah: 1 Candle",
"2025-12-15 Chanukah: 2 Candles",
...
]
```
**Usage Examples:**
- "Give me a list of all upcoming holidays"
- "What are the holidays until the end of the year?"
- "Show me all the holidays"
**Example Response:**
```
Here are all the upcoming holidays until the end of the year:
November 2025:
- November 20 - Sigd
- November 26 - Ben-Gurion Day
December 2025:
- December 14 - Chanukah: 1st Candle
- December 15 - Chanukah: 2nd Candle
- December 16 - Chanukah: 3rd Candle
- December 17 - Chanukah: 4th Candle
- December 18 - Chanukah: 5th Candle
- December 19 - Chanukah: 6th Candle
- December 20 - Chag HaBanot and Chanukah: 7th Candle
- December 21 - Chanukah: 8th Candle
- December 22 - Chanukah: 8th Day
- December 30 - Asara B'Tevet (Fast)
Happy Holidays! 🕎
```
---
## Natural Language Interaction Examples
The beauty of this MCP server is that you can ask questions in natural language, and Claude will understand and provide the information in a conversational way.
### Shabbat Times Queries
**Q:** "When is candle lighting in Ashdod?"
**A:** "Shabbat candle lighting in Ashdod is on Friday, November 14, 2025 at 16:24..."
**Q:** "What time does Shabbat end in Tel Aviv this week?"
**A:** "Havdalah (Shabbat end) in Tel Aviv will be on Saturday, November 15 at 17:19..."
### Holiday Queries
**Q:** "What's the next Jewish holiday?"
**A:** "The next holiday is Sigd on Thursday, November 20, 2025. Sigd is a holiday celebrated by Ethiopian Jews..."
**Q:** "When does Chanukah start this year?"
**A:** "Chanukah starts on December 14, 2025 with the lighting of the first candle..."
### Multi-City Queries
**Q:** "Compare Shabbat times in Jerusalem and Eilat"
**A:** Claude will call the tool twice and provide a comparison of both cities
### Contextual Questions
You can also ask follow-up questions:
- "What about next week?" (after asking about Shabbat times)
- "And the holiday after that?" (after asking about the next holiday)
- "What time in Haifa?" (after discussing Shabbat times in another city)
Claude maintains context and understands what you're referring to!
---
## Troubleshooting
### Server Doesn't Appear in Claude Desktop
1. Verify the file path is correct and has no typos
2. Check that `uv` is installed and accessible: `uv --version`
3. Ensure dependencies are installed: `uv add fastmcp requests`
4. Try restarting Claude Desktop
### Runtime Errors
If you encounter errors, check:
- The JSON file is valid (no extra commas)
- All brackets are properly closed
- The path doesn't contain spaces without quotes
### Testing the Server Manually
You can run the server directly for testing:
```bash
uv run hebcal_server.py
```
## Data Source
Information comes from [Hebcal.com](https://www.hebcal.com/) - a reliable source for Hebrew calendar information.
## License
This code uses Hebcal's public API. Please review Hebcal's terms of service for commercial use.
---
**Notes:**
- Shabbat times are calculated separately for each city
- Times are automatically updated according to the Hebrew and civil calendars
- Information includes holidays, Rosh Chodesh, and other special days
