Azan-MCP

Azan-MCP

Azan-MCP is an open-source Model Context Protocol (MCP) 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.

What it does

• 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).

• 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.

• 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).

• 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.

• 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.

• 99 Names of Allah — The complete Asma ul-Husna with Arabic text, transliteration, meaning, and explanation for all 99 names, fully searchable.

Design principles

Tech Stack

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.

Folder Structure

src/azan_mcp/
├── server.py          # FastMCP entry point — 34 tools across 6 modules
├── config.py          # UserConfig dataclass (location, timezone, method, madhab)
├── prayer_engine.py   # Vendored Meeus solar algorithm
├── tools/             # One module per epic: prayer_times, azan, calendar,
│                      #   dua_dhikr, calculators, asma
└── data/              # adhkar.json · duas.json · asma_ul_husna.json

Supported Calculation Methods

Tools

Quickstart

uvx azan-mcp

Or with a config file:

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

Claude Desktop Setup

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "azan": {
      "command": "uvx",
      "args": ["azan-mcp"],
      "env": {
        "AZAN_CONFIG": "/path/to/your/azan-config.json"
      }
    }
  }
}

Configuration

Create an azan-config.json file (see examples/azan-config.example.json):

{
  "latitude": 21.3891,
  "longitude": 39.8579,
  "timezone": "Asia/Riyadh",
  "calculation_method": "umm_al_qura",
  "madhab": "shafi",
  "iqama_offsets": {
    "fajr": 20, "dhuhr": 10, "asr": 10, "maghrib": 5, "isha": 15
  }
}

Development

uv sync
uv run pytest tests/ -v --ignore=tests/test_integration.py

License

This project is licensed under the MIT License — see the LICENSE file for details.

MIT License

Copyright (c) 2026 Azan-MCP Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.