azan-mcp: An MCP Server That Puts Prayer Times Behind a Tool Call
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.
At a glance
- What is it?
- azan-mcp is a Python MCP server that exposes 34 Islamic utilities, from prayer times to Faraid inheritance, to any LLM client that speaks the Model Context Protocol. The interesting question is not whether it calculates prayer times correctly, but whether an LLM belongs in that calculation path at all.
- Who is it for?
- Adopt azan-mcp if you are building an MCP client and want prayer times, Hijri conversion and adhkar available to an agent without writing the astronomy or the hadith sourcing yourself. Do not adopt it if you need a prayer times library to call directly from application code, or if you need a calculation convention outside the ten listed.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 106 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem is not the astronomy, it is the agent's blind spot
An LLM asked when Maghrib is in Kuala Lumpur has three options. It can refuse. It can guess, which is worse. Or it can call a tool. The last option requires someone to have written the tool, and that someone has to handle solar declination, the difference between Hanafi and Shafi Asr shadow ratios, the fact that Umm al-Qura uses a fixed 90 minute interval after Maghrib for Isha rather than an angle, and the timezone database. azan-mcp exists so that the person writing the agent does not have to be that someone.
The audience is narrow and specific. This is not a prayer times library for a mobile app. It is an MCP server, and MCP is the protocol Anthropic published for connecting language models to external tools. The README names Claude Desktop as the target client and says any LLM client that supports MCP can use it. If you are building an agent that needs to answer Islamic questions with a location and timezone attached, this is the layer you would otherwise build yourself. If you are building a prayer app, you are in the wrong repository, and the alternative section below explains why.
What actually runs when the model calls get_prayer_times
The repository layout is small enough to describe without hand-waving. src/azan_mcp/server.py is the FastMCP entry point and registers 34 tools across six modules under tools/: prayer_times, azan, calendar, dua_dhikr, calculators and asma. A UserConfig dataclass in config.py holds location, timezone, calculation method and madhab. prayer_engine.py contains a vendored implementation of the Meeus solar algorithm, written against the standard library only (math, datetime, zoneinfo). The data directory holds three JSON files: adhkar.json, duas.json and asma_ul_husna.json.
The vendoring decision is the one worth pausing on. The README states the engine uses Python's standard library only with "no stale third-party astronomical dependency." That is a defensible call. Astronomical libraries go unmaintained, and a prayer time that drifts by two minutes because a dependency stopped updating its delta-T tables is a hard bug to trace. The cost is that the algorithm now lives in this repository and moves only when its maintainer moves it. The README claims accuracy of plus or minus two minutes against IslamicFinder. That number is a documentation claim, not something I verified, and IslamicFinder is itself a calculation service rather than a reference ephemeris, so the comparison is between two implementations rather than against an observatory.
The Hijri side takes the opposite approach. The README says conversion uses the hijridate library, which it describes as actively maintained. So the project vendors where the dependency is fragile and delegates where the dependency is healthy. That is a coherent split, and it is stated plainly enough that you can audit the choice.
The meta block is the design decision that matters most
Every tool response includes a meta block stating the calculation method, madhab, source and confidence that produced the answer. This is the part of the design I would point at first. Prayer time disagreements between mosques are usually disagreements about method, not about arithmetic, and an agent that returns a time without saying which method produced it is giving an answer that cannot be checked. The same applies to the du'a and dhikr data: the README says each entry carries a hadith reference and a confidence level, with high meaning Bukhari or Muslim and medium meaning the Sunan books. That is a coarse two-level scale, and it is honest about being coarse.
The discoverability tools follow from the same instinct. list_calculation_methods returns all ten method IDs with their Fajr and Isha angles. list_dua_topics enumerates the topics so the model does not invent a category that does not exist. Both exist because an LLM will hallucinate a plausible parameter name if you let it, and the cheapest fix is a tool that returns the valid set. The calculators carry a different safeguard: the README states that Zakat, Faraid and calendar tools include a "consult a qualified scholar" disclaimer in every response. Whether a disclaimer in a tool result changes model behaviour is an open question, but its presence at least means the project is not pretending Faraid distribution is a solved arithmetic problem.
Getting it running: uvx, config, and the method table
The README gives a single install path: uvx azan-mcp. No npm, no Docker, no manual setup, in its words. uvx runs a Python package from PyPI in an ephemeral environment, so the practical requirement is that uv is installed and that Python 3.12 or later is available, since the badge and tech stack section both state 3.12+.
Configuration is a UserConfig dataclass with four fields: location, timezone, method and madhab. The README does not show the file format or the environment variable names that populate it, and that is a real gap for anyone trying to deploy this headlessly. What it does document is the method table, which is worth reading before you pick a value. Ten IDs are listed with their Fajr and Isha parameters: umm_al_qura at 18.5 degrees with Isha fixed at 90 minutes after Maghrib, mwl at 18 and 17, isna at 15 and 15, egypt at 19.5 and 17.5, karachi at 18 and 18, tehran at 17.7 and 14, kuwait at 18 and 17.5, uoif at 12 and 12, ithna_ashari at 16 and 14, and muhammadiyah at 20 and 18.
The spread is the point. Fajr angles run from 12 degrees for UOIF to 20 for Muhammadiyah, and at high latitudes that difference moves Fajr by a substantial margin. Asr is governed separately by the madhab setting, Hanafi or Shafi. If you deploy this without setting the method explicitly, you are choosing a convention on your users' behalf, and the README does not say what the default is. Set it.
Where it breaks: high latitudes, silent defaults, and a release history that deserves a second look
The method table has no high-latitude rule. Every entry is an angle pair or a fixed interval, and none of the ten names an adjustment for the weeks around the solstices when the sun never reaches 18 degrees below the horizon at, say, Tromso. Some prayer time implementations offer a middle-of-the-night or one-seventh rule for exactly this case. The README does not mention one. If your users are above roughly 48 degrees latitude, verify what the engine returns in June before trusting it, because an angle-based Fajr with no fallback can produce a time that does not exist.
The default configuration is the second gap. get_server_info exists to report the active location, timezone, method and madhab, which implies the server starts with some default rather than requiring configuration. A default timezone in a tool that computes prayer times is a correctness hazard, because a wrong timezone shifts every prayer by hours while the output still looks well-formed. Call get_server_info first in any deployment.
Third, the release history does not line up with the README. The most recent release listed is 3.0.0 from April 2019, described as a fix for a bug in method calculations. Before that, 2.2 in March 2017 fixed the Muhammadiyah calculation method, and 2.1 came six days earlier. The repository's last push is dated 2026, and the README describes Python 3.12+ and FastMCP, which did not exist in 2019. The straightforward reading is that development has continued on main without tagged releases, so the PyPI version you get from uvx azan-mcp may not correspond to what the README describes. Two of the three tagged releases are corrections to calculation methods. That pattern is worth knowing before you assume the angles are settled.
The alternative is not another MCP server, it is a library
The closest comparison is the adhan family of prayer time libraries, which exist as standalone packages in several languages and are typically consumed by calling a function from application code. The difference in approach is architectural rather than numerical. A library hands you a function that returns a struct; you decide where the location comes from, how the result is cached, and what happens when the user changes timezone. azan-mcp hands an LLM a tool with a JSON schema and a meta block, and the LLM decides when to call it and how to phrase the answer.
That difference cuts both ways. If your application already knows the user's coordinates and needs a prayer time to display in a widget, the MCP layer is pure overhead: you are serialising a request through a model that may rephrase the number. If your application is a conversational agent that has to decide on its own whether the user is asking about prayer times at all, the tool schema is doing real work that a library call cannot do, because a library call has to be placed in code by someone who already knew the intent.
The other distinction is scope. A prayer times library computes prayer times. azan-mcp also converts Hijri dates, returns adhkar with hadith references, computes zakat and distributes inheritance under Faraid. Those are separate concerns bundled behind one server, and the bundling is what makes the disclaimer requirement coherent: the same process that tells you Maghrib is at 19:42 also tells you to consult a scholar about your inheritance split. Whether you want one server holding both is a deployment question, not a correctness one.
Maintenance cost, licence, and what to check before you commit
The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of the licence implication here, and it is not legal advice; read the LICENSE file in the repository for the operative text. MIT is compatible with vendoring into a closed product, which matters given that prayer_engine.py is itself vendored code.
The maintenance picture is mixed in a way the README does not address. The vendored Meeus engine means no upstream astronomical dependency to track, but it also means no upstream to inherit fixes from. The hijridate dependency is the opposite: it moves on its own schedule and a breaking change there lands in your build. The data files are static JSON, so the adhkar and du'a collections only change when someone edits them, and the hadith references will not update themselves.
The upgrade cost is concentrated in one place. Because the tagged releases stop in 2019 while the README describes a FastMCP-based Python 3.12 project, pinning to a version number may not give you the code the README documents. Check what uvx azan-mcp actually resolves to before you build on it, and read the method table against your users' convention rather than assuming the default matches. The tool that tells you which method is active is get_server_info, and it is the first one worth calling.
Editorial conclusion
Adopt azan-mcp if you are building an MCP client and want prayer times, Hijri conversion and adhkar available to an agent without writing the astronomy or the hadith sourcing yourself. Do not adopt it if you need a prayer times library to call directly from application code, or if you need a calculation convention outside the ten listed. Before wiring it into anything, call list_calculation_methods and get_server_info to confirm which method and madhab your deployment actually resolves to, because the defaults are not stated in the README and the release history suggests the method calculations have been corrected more than once.
Community notes