Skip to content
Back to search

azan-mcp

Azan + Prayer Time + MCP + AI Agents + Islamic + Salah + A lightweight MCP library to calculate prayer times and trigger Azan with a single tool call. If you’re building an AI agent or prayer application, there’s no need to deal with astronomical calculations, timezones, or edge cases again.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ahmedeltaher--azan-mcp/badge.svg)](/listings/ahmedeltaher--azan-mcp)

HTML

<a href="/listings/ahmedeltaher--azan-mcp"><img src="/api/listings/ahmedeltaher--azan-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

uvx azan-mcp

Or with a config file:

AZAN_CONFIG=/path/to/azan-config.json uvx azan-mcp

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 198 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Azan-MCP
  2. ![License](https://img.shields.io/badge/License-MIT-yellow.svg)
  3. ![Python](https://img.shields.io/badge/Python-3.12+-blue.svg)
  4. ![MCP](https://img.shields.io/badge/MCP-FastMCP-brightgreen.svg)
  5. ![Tools](https://img.shields.io/badge/Tools-34%20Islamic%20Tools-green.svg)
  6. ![Tests](https://img.shields.io/badge/Tests-62%20passing-brightgreen.svg)
  7. ![PyPI](https://img.shields.io/badge/PyPI-azan--mcp-blue.svg)
  8. ![Hijri](https://img.shields.io/badge/Calendar-Hijri%20%2B%20Gregorian-orange.svg)
  9. ![Methods](https://img.shields.io/badge/Calculation-10%20Methods-lightgrey.svg)
  10. **Azan-MCP** is an open-source [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that brings a comprehensive suite of Islamic utilities directly into AI assistants such as Claude Desktop. It enables any LLM client that supports MCP to answer Islamic questions with accuracy, proper sourcing, and full awareness of the user's location, timezone, and madhab.
  11. ### What it does
  12. - **Prayer Times** — Calculates the five daily prayers (Fajr, Dhuhr, Asr, Maghrib, Isha) plus Sunrise for any location on Earth using the full Meeus solar algorithm. Supports 10 internationally recognised calculation methods and both Hanafi and Shafi madhab for Asr. Also computes Qibla direction, monthly calendars, and Sunnah prayer windows (Duha, Awwabin, Tahajjud).
  13. - **Azan & Iqama** — Returns the full Azan text in Arabic and transliteration (with the Fajr Tatwidh variant), calculates Iqama times based on configurable per-prayer offsets, and provides a complete daily Azan schedule.
  14. - **Islamic Calendar** — Converts dates between Gregorian and Hijri calendars, lists named Islamic events with their Gregorian equivalents, and identifies recommended voluntary fasting days (Mondays/Thursdays, Ayyam al-Beed, 6 days of Shawwal, Day of Arafah).
  15. - **Du'a & Dhikr** — Provides sourced morning and evening adhkar, du'a collections across 15 topics (travel, eating, anxiety, protection, and more), and du'as for every position in salah. Every entry is traced to its hadith reference with a confidence rating.
  16. - **Zakat & Islamic Calculators** — Calculates Zakat due on cash, gold, silver, and trade goods; determines Nisab thresholds; computes Suhoor/Iftar times for Ramadan date ranges; and distributes inheritance according to Faraid (Quran 4:11-12) using exact fractional arithmetic with Aul handling.
  17. - **99 Names of Allah** — The complete Asma ul-Husna with Arabic text, transliteration, meaning, and explanation for all 99 names, fully searchable.
  18. ---
  19. ![MCP Architecture](MCP%20image.png)
  20. ### Design principles
  21. | Principle | How it is applied |
  22. |-----------|------------------|
  23. | **Accuracy** | Prayer engine implements the full Meeus astronomical algorithm (±2 min vs IslamicFinder). Hijri conversion uses the `hijridate` library. |
  24. | **Authenticity** | Every Du'a and Dhikr entry carries a hadith source reference and a confidence level (`high` = Bukhari/Muslim, `medium` = Sunan books). |
  25. | **Transparency** | All tool responses include a `meta` block stating the calculation method, madhab, source, and confidence used. |
  26. | **Discoverability** | Tools like `list_dua_topics` and `list_calculation_methods` prevent the LLM from guessing invalid inputs. |
  27. | **Safety** | Zakat, Faraid, and calendar tools include a "consult a qualified scholar" disclaimer in every response. |
  28. | **Zero friction** | Installable with a single `uvx azan-mcp` command — no npm, no Docker, no manual setup. |
  29. ### Tech Stack
  30. Built with **Python 3.12+** and **FastMCP** (the official Anthropic MCP SDK). The prayer time engine is vendored directly from the Meeus algorithm using Python's standard library only (`math`, `datetime`, `zoneinfo`) — no stale third-party astronomical dependency. The Hijri calendar uses the actively maintained `hijridate` package.
  31. ### Folder Structure
  32. ```
  33. src/azan_mcp/
  34. ├── server.py # FastMCP entry point — 34 tools across 6 modules
  35. ├── config.py # UserConfig dataclass (location, timezone, method, madhab)
  36. ├── prayer_engine.py # Vendored Meeus solar algorithm
  37. ├── tools/ # One module per epic: prayer_times, azan, calendar,
  38. │ # dua_dhikr, calculators, asma
  39. └── data/ # adhkar.json · duas.json · asma_ul_husna.json
  40. ```
  41. ---
  42. ## Supported Calculation Methods
  43. | ID | Name | Fajr° | Isha |
  44. |----|------|-------|------|
  45. | `umm_al_qura` | Umm al-Qura, Makkah | 18.5 | 90 min after Maghrib |
  46. | `mwl` | Muslim World League | 18 | 17° |
  47. | `isna` | ISNA | 15 | 15° |
  48. | `egypt` | Egyptian General Authority | 19.5 | 17.5° |
  49. | `karachi` | Univ. of Islamic Sciences, Karachi | 18 | 18° |
  50. | `tehran` | Univ. of Tehran | 17.7 | 14° |
  51. | `kuwait` | Kuwait | 18 | 17.5° |
  52. | `uoif` | UOIF (France) | 12 | 12° |
  53. | `ithna_ashari` | Ithna Ashari | 16 | 14° |
  54. | `muhammadiyah` | Muhammadiyah | 20 | 18° |
  55. ## Tools
  56. | # | Tool | Category | Description |
  57. |---|------|----------|-------------|
  58. | 1 | `get_server_info` | Core | Active config: location, timezone, calculation method, madhab |
  59. | 2 | `list_calculation_methods` | Core | All 10 method IDs with Fajr/Isha angles |
  60. | 3 | `get_prayer_times` | Prayer Times | All 5 prayers + Sunrise for a date and location |
  61. | 4 | `get_next_prayer` | Prayer Times | Name and time of the next upcoming prayer |
  62. | 5 | `get_time_until_next_prayer` | Prayer Times | Minutes until next prayer + human-readable countdown |
  63. | 6 | `get_qibla_direction` | Prayer Times | Bearing in degrees + 16-point cardinal toward Makkah |
  64. | 7 | `get_monthly_prayer_calendar` | Prayer Times | Full month prayer schedule (28–31 days) |
  65. | 8 | `get_sunnah_prayer_times` | Prayer Times | Duha, Awwabin, and Tahajjud time windows |
  66. | 9 | `get_azan_text` | Azan & Iqama | Full Azan text in Arabic and/or transliteration (Fajr variant included) |
  67. | 10 | `get_iqama_time` | Azan & Iqama | Iqama time = adhan + configured offset |
  68. | 11 | `set_iqama_offset` | Azan & Iqama | Update iqama delay (minutes after adhan) per prayer |
  69. | 12 | `get_daily_azan_schedule` | Azan & Iqama | All 5 adhan + iqama times for today |
  70. | 13 | `get_hijri_date` | Islamic Calendar | Today's or a given date's Hijri equivalent |
  71. | 14 | `convert_gregorian_to_hijri` | Islamic Calendar | Gregorian → Hijri conversion |
  72. | 15 | `convert_hijri_to_gregorian` | Islamic Calendar | Hijri → Gregorian conversion |
  73. | 16 | `get_islamic_events` | Islamic Calendar | Named Islamic events for a Hijri year/month with Gregorian dates |
  74. | 17 | `get_ramadan_dates` | Islamic Calendar | Gregorian start and end dates of Ramadan for a given year |
  75. | 18 | `get_eid_dates` | Islamic Calendar | Eid al-Fitr and Eid al-Adha dates for a given year |
  76. | 19 | `get_voluntary_fasting_dates` | Islamic Calendar | Mondays/Thursdays, Ayyam al-Beed, 6 Shawwal, Day of Arafah |
  77. | 20 | `get_morning_adhkar` | Du'a & Dhikr | Complete morning adhkar with Arabic, transliteration, source |
  78. | 21 | `get_evening_adhkar` | Du'a & Dhikr | Complete evening adhkar with Arabic, transliteration, source |
  79. | 22 | `list_dua_topics` | Du'a & Dhikr | All available topic slugs (travel, eating, anxiety, …) |
  80. | 23 | `get_dua_by_topic` | Du'a & Dhikr | All du'as for a given topic |
  81. | 24 | `search_dua` | Du'a & Dhikr | Full-text search across Arabic, transliteration, translation |
  82. | 25 | `get_counter_recommendation` | Du'a & Dhikr | Recommended repetition count and virtues for a dhikr |
  83. | 26 | `get_prayer_dua` | Du'a & Dhikr | Du'as for ruku, sujood, tashahhud, and after salah |
  84. | 27 | `calculate_zakat` | Zakat & Calculators | 2.5% Zakat due on cash, gold, silver, or trade goods above nisab |
  85. | 28 | `calculate_gold_nisab` | Zakat & Calculators | Nisab threshold = 85g × gold price per gram |
  86. | 29 | `calculate_silver_nisab` | Zakat & Calculators | Nisab threshold = 595g × silver price per gram |
  87. | 30 | `calculate_fasting_times` | Zakat & Calculators | Suhoor (Fajr) and Iftar (Maghrib) for a date range (max 31 days) |
  88. | 31 | `calculate_inheritance_basic` | Zakat & Calculators | Faraid fixed shares with Aul handling (Quran 4:11-12) |
  89. | 32 | `get_asma_ul_husna` | 99 Names | All 99 Names of Allah with Arabic, transliteration, and meaning |
  90. | 33 | `get_name_of_allah` | 99 Names | Look up a name by number (1–99) or transliteration |
  91. | 34 | `search_asma_ul_husna` | 99 Names | Search names by meaning, transliteration, or Arabic text |
  92. ## Quickstart
  93. ```bash
  94. uvx azan-mcp
  95. ```
  96. Or with a config file:
  97. ```bash
  98. AZAN_CONFIG=/path/to/azan-config.json uvx azan-mcp
  99. ```
  100. ## Claude Desktop Setup
  101. Add to your `claude_desktop_config.json`:
  102. ```json
  103. {
  104. "mcpServers": {
  105. "azan": {
  106. "command": "uvx",
  107. "args": ["azan-mcp"],
  108. "env": {
  109. "AZAN_CONFIG": "/path/to/your/azan-config.json"
  110. }
  111. }
  112. }
  113. }
  114. ```
  115. ## Configuration
  116. Create an `azan-config.json` file (see `examples/azan-config.example.json`):
  117. ```json
  118. {
  119. "latitude": 21.3891,
  120. "longitude": 39.8579,
  121. "timezone": "Asia/Riyadh",
  122. "calculation_method": "umm_al_qura",
  123. "madhab": "shafi",
  124. "iqama_offsets": {
  125. "fajr": 20, "dhuhr": 10, "asr": 10, "maghrib": 5, "isha": 15
  126. }
  127. }
  128. ```
  129. ## Development
  130. ```bash
  131. uv sync
  132. uv run pytest tests/ -v --ignore=tests/test_integration.py
  133. ```
  134. ## License
  135. This project is licensed under the **MIT License** — see the [LICENSE](LICENSE) file for details.
  136. ```
  137. MIT License
  138. Copyright (c) 2026 Azan-MCP Contributors
  139. Permission is hereby granted, free of charge, to any person obtaining a copy
  140. of this software and associated documentation files (the "Software"), to deal
  141. in the Software without restriction, including without limitation the rights
  142. to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  143. copies of the Software, and to permit persons to whom the Software is
  144. furnished to do so, subject to the following conditions:
  145. The above copyright notice and this permission notice shall be included in all
  146. copies or substantial portions of the Software.
  147. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  148. IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  149. FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  150. AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  151. LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  152. OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  153. SOFTWARE.
  154. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.