Metadata-Version: 2.4
Name: esolat-mcp
Version: 1.0.2
Summary: MCP server for prayer times (JAKIM/global), nearest mosque finder, and Islamic calendar events
Author: Zubir Jamal
License-Expression: MIT
Project-URL: Homepage, https://github.com/zubir2k/esolat-mcp
Project-URL: Repository, https://github.com/zubir2k/esolat-mcp
Project-URL: Issues, https://github.com/zubir2k/esolat-mcp/issues
Keywords: mcp,mcp-server,jakim,esolat,prayer-times,malaysia,islamic-calendar,mosque
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Religion
Classifier: Topic :: Communications
Classifier: Intended Audience :: Developers
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]<2.0,>=1.23.0
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]
Requires-Dist: httpx
Requires-Dist: cachetools>=5.0
Dynamic: license-file

![eSolatMCP](https://github.com/user-attachments/assets/0ad3b631-1f0d-4906-9e9e-442a009ff89e)

[![GitHub Repo stars](https://img.shields.io/github/stars/zubir2k/esolat-mcp?style=social)](https://github.com/zubir2k/esolat-mcp/stargazers)
![MCP](https://img.shields.io/badge/MCP-Compatible-blue)
![Python](https://img.shields.io/badge/Python-3.11+-blue)
![Docker](https://img.shields.io/badge/Docker-Supported-blue)
[![Buy](https://img.shields.io/badge/Belanja-Coffee-yellow.svg)](https://zubirco.de/buymecoffee)

**MCP server for accurate Malaysian prayer times (official JAKIM/e-Solat), nearest masjid and surau, and Islamic calendar events.**

Gives AI assistants like **Claude Desktop** and **Claude Code** reliable, hallucination-free access to Islamic worship tools with smart Malaysia-first routing.

## Features

- **Official JAKIM data** for Malaysia (via `Waktusolat.app API`)
- **Dhuha time** automatically calculated (+28 minutes after Syuruk)
- **Malay Hijri month names** (Muharram, Safar, etc.)
- **Global fallback** using Aladhan API
- **Nearest mosques/suraus** with Google Maps + Waze deep links
- **Yearly Islamic events** (Eid, etc.)
- Dual mode: **Local (stdio)** + **Remote (Docker + secure HTTP)**
- Health dashboard for upstream APIs

## Tools

The server registers three powerful tools that Claude can discover and call automatically:

1. **`get_monthly_prayer_times`**
   - Get full monthly prayer schedule (Fajr, Syuruk, Dhuha, Dhuhr, Asr, Maghrib, Isha)
   - Accepts place name or latitude/longitude
   - Returns both Gregorian and Hijri dates

2. **`find_nearest_mosques`**
   - Find up to 15 nearest masjid/surau
   - Default radius: 5 km (configurable)
   - Malaysia uses official e-Solat data; global uses OpenStreetMap
   - Includes distance, coordinates, Google Maps & Waze links

3. **`get_yearly_islamic_events`**
   - Major Islamic dates and holidays for a given year
   - Malaysia-aware routing

## Quick Start

### Option 1: Local / Stdio Mode (Recommended for Claude Desktop)

**No clone needed:**
```bash
uvx esolat-mcp
```

**Claude Desktop config example:**
```JSON
{
  "mcpServers": {
     "esolat": {
      "command": "uvx",
      "args": ["esolat-mcp"]
    }
  }
}
```

### Option 2: Docker / Remote HTTP Mode (Self-hosted)

**1. Clone the repo and set up token:**
```Bash
git clone https://github.com/zubir2k/esolat-mcp.git
cd esolat-mcp
cp .env.example .env
```

**2. Generate a strong token:**
```Bash
python -c "import secrets; print(secrets.token_urlsafe(32))"
# or: openssl rand -hex 32
```

**3. Paste it into `.env` as `MCP_WEBHOOK_TOKEN=your_token_here`**

**4. Build and Start the container:**
```Bash
docker build -t esolat-mcp:latest .
docker compose up -d
```
**5. Endpoints**

**- Streamable MCP HTTP Endpoint (main one for AI clients):**
```
http://your-server-ip:8626/api/webhook/<MCP_WEBHOOK_TOKEN>/mcp
```
**- Health Dashboard (useful for monitoring):**
```
http://your-server-ip:8626/api/webhook/<MCP_WEBHOOK_TOKEN>
```
(GET request without /mcp — shows status of JAKIM, Aladhan, and Overpass APIs)

> [!WARNING]
> Always keep your `MCP_WEBHOOK_TOKEN` secret.
> The token is part of the URL path for simple authentication. You can change the local port via the `PORT` environment variable.
> 
> **For production:** Consider using a reverse proxy (Nginx/Cloudflare) with HTTPS to prevent the token from being intercepted or leaked in access logs.

> [!TIP]
> **Prefer a simpler setup?**
> If you want a no-server, no-Docker solution that runs on the edge, consider my **Cloudflare Worker edition** (free tier eligible). It automatically enforces HTTPS and avoids the self-hosting risks mentioned above.
> 
> 👉 Head over to the repo: [zubir2k/esolat-cfworker](https://github.com/zubir2k/esolat-cfworker)

## Usage Examples (Claude)
### Prayer Times

_"What are today's prayer times in Kuala Lumpur?" \
"Show me full prayer schedule for Penang this Ramadan." \
"Prayer times for Kota Kinabalu next week."_

### Mosques

_"Find the nearest mosque to me." \
"Mosques within 10km of Petaling Jaya." \
"Nearest surau from KLCC."_

### Events & Planning

_"Major Islamic events in 2026 for Malaysia." \
"Plan my trip to Johor Bahru: prayer times + nearest mosques + Eid dates."_

## Visual
### Claude Config
![Config](https://github.com/user-attachments/assets/5cdca516-0b5d-4782-85e0-2c1ee0360b6a)

### Claude Prompt
![Prompt](https://github.com/user-attachments/assets/387213a0-6dc4-4c0e-a3ad-339277019255)


## Credits

- [e-solat](https://www.e-solat.gov.my/) JAKIM - For the official prayer times
- [WaktuSolat.app](https://waktusolat.app/) - Prayer Time by GPS
- [Model Context Protocol](https://modelcontextprotocol.io/) - For the MCP framework

## License

This project is licensed under the MIT License.

## Disclaimer & Data Source

### Important Notice & Reliability Disclaimer
This integration pulls data directly from the official **e-Solat JAKIM (Department of Islamic Development Malaysia)** portal. However, please note:

- **No Liability:** This integration is a community-driven project provided "as is" without any guarantees. The maintainer is **not solely or legally responsible** for any discrepancies, inaccuracies, delays, or omissions in prayer times or calendar dates.
- **Verify Important Times:** Users are strictly advised to regularly check and verify times against the official **[JAKIM eSolat Portal](https://www.e-solat.gov.my/)** or official local announcements, especially for critical obligations (e.g., fasting, community prayers).
- **Network & Upstream Dependencies:** Synchronization depends on upstream API availability and local network connectivity. Discrepancies caused by unexpected server updates from JAKIM or local server downtime are outside the control of this software.

*By using this tool, you acknowledge and agree that the developer holds no liability for missed schedules or data inaccuracies.*
