# 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