🕌 Muslim Prayer Reminder MCP

Production-ready astronomical prayer calculation and proactive notification engine on Cloudflare Workers for AI models, coding agents, and developer environments.

Documentation • Live Demo (1080p) • Quick Start • Tools Catalog • Theological Rigor • Security Policy

Project Status: 🟢 Actively Maintained (v1.0.1)
Supported across Cloudflare Workers, Node.js 22/24 (Ubuntu & Windows), and all Model Context Protocol (MCP) clients.

⚡ Quick Start

1. Run via NPX (Zero Installation)

Add to your Claude Desktop, Cursor, or VS Code MCP configuration:

config.json

{
  "mcpServers": {
    "muslim-prayer": {
      "command": "npx",
      "args": ["-y", "muslim-prayer-mcp"]
    }
  }
}

2. Connect via Remote Streamable HTTP (Cloudflare Workers)

config.json

{
  "mcpServers": {
    "muslim-prayer": {
      "url": "https://muslim-prayer-mcp.najetareqz.workers.dev/mcp"
    }
  }
}

3. 1-Click Install in Cursor

📺 Live Video Demonstration

Watch the Muslim Prayer Reminder MCP in action inside ChatGPT, Claude, and Cursor:

👉 Click here to watch the full 1080p demo video (MP4)

🏛️ System Architecture

mermaid

flowchart TD
    subgraph ClientLayer ["AI Clients & Environments"]
        Cursor["Cursor IDE"]
        Claude["Claude Desktop / Web"]
        ChatGPT["ChatGPT Apps Directory"]
        Agent["Autonomous AI Agent"]
    end

    subgraph TransportLayer ["Model Context Protocol"]
        HTTP["Streamable HTTP /mcp"]
        Stdio["Stdio Transport CLI"]
    end

    subgraph ResolverLayer ["Layered Location Resolver"]
        Explicit["Explicit Lat/Lng"] --> Truncate["2-Decimal Sanitizer ~1.1km"]
        UserPref["Stored KV Preferences"] --> Resolver["Location Normalizer"]
        Headers["X-Forwarded Headers"] --> Resolver
        GeoIP["Cloudflare request.cf GeoIP"] --> Resolver
        Fallback["Makkah Al-Mukarramah Fallback"] --> Resolver
        Truncate --> Resolver
    end

    subgraph EngineLayer ["In-Isolate Solar Calculation Engine"]
        Resolver --> Authority["Authority Selector"]
        Authority --> AdhanEngine["Astronomical Solar Solver"]
        AdhanEngine --> FiqhRules["Fiqh Clamping 48° & Madhab Calibration"]
        FiqhRules --> DueLogic["Prayer Window & Due Evaluator"]
    end

    subgraph OutputLayer ["Formatted Payloads & Disclosures"]
        DueLogic --> MCPResponse["JSON-RPC Structured Output"]
        MCPResponse --> DisclosureNotice["Mandatory Theological Notice"]
        DisclosureNotice --> Middleware["Deterministic Host Middleware"]
        Middleware --> FinalOutput["Appended AI Response: 🕌 It is time for Maghrib prayer"]
    end

    ClientLayer --> TransportLayer
    TransportLayer --> ResolverLayer

🛠️ MCP Tools Catalog

The server exposes 5 finely-tuned tools conforming to the latest Model Context Protocol standard with full Zod output contracts:

Tool Name	Operation Mode	Open World	Description
`get_prayer_status`	Read-Only	Safe	Checks if an obligatory prayer is currently due. Returns active prayer, countdown, calculation authority, and selection justification.
`get_today_prayer_times`	Read-Only	Safe	Computes today's full timetable (Fajr, Sunrise, Dhuhr, Asr, Maghrib, Isha) in UTC and localized string format.
`get_next_prayer`	Read-Only	Safe	Returns the immediate upcoming prayer, exact scheduled timestamp, countdown minutes, and regional authority.
`search_cities`	Read-Only	Safe	Fuzzy search across 100+ global Islamic metropolitan areas with pre-calibrated coordinates, timezones, and authorities.
`list_authorities`	Read-Only	Safe	Enumerates all recognized Islamic calculation authorities, twilight angles, and regional jurisdictions.

📐 Astronomical & Theological Rigor

Prayer calculations are not approximations—they represent exact solar depression angles calibrated to regional fatwa bodies:

Sovereign Authority	Jurisdiction	Fajr Angle	Isha Angle / Interval	Default Asr Madhab
Umm al-Qura University	Saudi Arabia, GCC	18.5°	+90 min (+120 min Ramadan)	Shafi / Standard
Egyptian General Survey	Egypt, Palestine, Levant	19.5°	17.5°	Shafi (Palestinian Awqaf offsets applied)
Diyanet İşleri Başkanlığı	Turkey, Balkans, Central Asia	18.0°	17.0°	Hanafi (Double shadow ratio)
Univ. of Islamic Sciences, Karachi	Pakistan, India, Bangladesh	18.0°	18.0°	Hanafi (Double shadow ratio)
ISNA	United States, Canada	15.0°	15.0°	Shafi / Standard
Muslim World League (MWL)	Europe, Global Fallback	18.0°	17.0°	Shafi / Standard
MABIMS / JAKIM / MUIS	Malaysia, Singapore, Indonesia	20.0°	18.0°	Shafi / Standard

High-Latitude Polar Adjustments

In latitudes above 48° North or South where twilight persists throughout the night in summer, the engine automatically engages fiqh-compliant clamping (Middle of the Night & One-Seventh Rule), preventing computational errors or impossible timetables.

🔌 Install & Multi-Agent Setup

Connect Muslim Prayer Reminder to any AI agent harness, developer IDE, or container runtime:

1-Click & Matrix Overview

Environment / Harness	Protocol Mode	Quick Command / Deeplink
Cursor IDE	Remote HTTP
Claude Code	Native Plugin	`/plugin marketplace add tareq7/muslim-prayer-mcp`
Codex	Native Plugin	`codex plugin marketplace add tareq7/muslim-prayer-mcp`
GitHub Copilot CLI	Copilot Plugin	`copilot plugin marketplace add tareq7/muslim-prayer-mcp`
Claude Desktop	Stdio CLI	`npx -y muslim-prayer-mcp` via `claude_desktop_config.json`
VS Code & Cline	Local NPX	`npx -y muslim-prayer-mcp` via `.vscode/mcp.json`
Windsurf & Devin	Remote HTTP	Remote URL to `mcp_config.json`
Gemini CLI	Native Extension	`gemini-cli --mcp-server https://.../mcp`
Pi Agent Harness	Git Extension	`pi install git:github.com/tareq7/muslim-prayer-mcp`
OpenCode	Agent Plugin	Auto-loaded via `opencode.json` & `AGENTS.md`
Docker Container	Container	`docker run -d -p 8080:8080 ghcr.io/tareq7/muslim-prayer-mcp:latest`

Claude Code

Run inside your Claude Code session:

bash

/plugin marketplace add tareq7/muslim-prayer-mcp
/plugin install muslim-prayer-mcp@muslim-prayer-mcp

(Note: Send as two separate prompts). In the Claude Code Desktop app, click the + button next to the prompt box ➔ Plugins ➔ Add plugin to browse and install from the marketplace.

Codex

Run in your terminal:

bash

codex plugin marketplace add tareq7/muslim-prayer-mcp
codex plugin add muslim-prayer-mcp@muslim-prayer-mcp

Run codex and open /hooks (or start a new thread). This also activates the plugin in the Codex Desktop app upon restart.

GitHub Copilot CLI

In your terminal:

bash

copilot plugin marketplace add tareq7/muslim-prayer-mcp
copilot plugin install muslim-prayer-mcp@muslim-prayer-mcp

Or inside an interactive Copilot CLI session:

text

/plugin marketplace add tareq7/muslim-prayer-mcp
/plugin install muslim-prayer-mcp@muslim-prayer-mcp

Cursor IDE

Click to install with one click:

Or manually add to .cursor/mcp.json:

config.json

{
  "mcpServers": {
    "muslim-prayer": {
      "url": "https://muslim-prayer-mcp.najetareqz.workers.dev/mcp"
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

config.json

{
  "mcpServers": {
    "muslim-prayer": {
      "command": "npx",
      "args": ["-y", "muslim-prayer-mcp"]
    }
  }
}

VS Code & Cline

Add to .vscode/mcp.json or Cline settings:

config.json

{
  "mcpServers": {
    "muslim-prayer": {
      "command": "npx",
      "args": ["-y", "muslim-prayer-mcp"]
    }
  }
}

Windsurf & Devin

Add to mcp_config.json:

config.json

{
  "mcpServers": {
    "muslim-prayer": {
      "url": "https://muslim-prayer-mcp.najetareqz.workers.dev/mcp"
    }
  }
}

Gemini CLI

Connect directly using the live edge endpoint:

bash

gemini-cli --mcp-server https://muslim-prayer-mcp.najetareqz.workers.dev/mcp

Pi Agent Harness

bash

pi install git:github.com/tareq7/muslim-prayer-mcp

OpenCode

Add to your opencode.json:

config.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "muslim-prayer": {
      "type": "remote",
      "url": "https://muslim-prayer-mcp.najetareqz.workers.dev/mcp"
    }
  }
}

OpenCode automatically loads this repository's AGENTS.md and skills/muslim-prayer-mcp/SKILL.md.

Docker Container

Terminal

docker run -d -p 8080:8080 ghcr.io/tareq7/muslim-prayer-mcp:latest

💻 Deterministic Host Middleware

For platforms building autonomous AI agents (Next.js, LangChain, Vercel AI SDK), the included middleware deterministically appends prayer notices to AI responses without hallucination:

server.ts

import { PrayerReminderMiddleware } from 'muslim-prayer-mcp/middleware';

const prayerMiddleware = new PrayerReminderMiddleware({
  workerBaseUrl: 'https://muslim-prayer-mcp.najetareqz.workers.dev',
  userId: 'user_session_42',
});

// Wrap any LLM completion
const rawLlmOutput = await callLlm('Can you review this pull request?');
const { responseText, reminderAppended } = await prayerMiddleware.processResponse(rawLlmOutput, {
  'X-User-Coordinates': '24.71, 46.68', // Riyadh
  'X-User-Timezone': 'Asia/Riyadh',
});

console.log(responseText);
// => The code looks solid, but let's optimize line 42...
//
// 🕌 It is time for Asr prayer.

🧪 Comprehensive Test Suite

The engine includes 44 unit, integration, and end-to-end tests validating astronomical accuracy across 10 worldwide benchmark coordinates:

Terminal

npm test

Code

▶ Astronomical Prayer Calculation Suite
  ✔ calculates valid prayer timetable for Riyadh in correct chronological sequence
  ✔ calculates valid prayer timetable for Makkah in correct chronological sequence
  ✔ calculates valid prayer timetable for Cairo in correct chronological sequence
  ✔ calculates valid prayer timetable for Dubai in correct chronological sequence
  ✔ calculates valid prayer timetable for London in correct chronological sequence
  ✔ calculates valid prayer timetable for Paris in correct chronological sequence
  ✔ calculates valid prayer timetable for New York in correct chronological sequence
  ✔ calculates valid prayer timetable for Jakarta in correct chronological sequence
  ✔ calculates valid prayer timetable for Karachi in correct chronological sequence
  ✔ calculates valid prayer timetable for Sydney (Southern Hem) in correct chronological sequence
  ✔ verifies Hanafi Asr is strictly later than Shafi Asr
  ✔ handles Daylight Saving Time (DST) transitions safely
  ✔ automatically resolves Palestinian Awqaf standard for Gaza
  ✔ handles high-latitude polar city with MiddleOfTheNight rule safely
...
ℹ tests 44 | pass 44 | fail 0

🔒 Security & Privacy Policy

Coordinate Truncation: All user coordinates are truncated to 2 decimal places upon arrival (~1.1 km resolution). Precise location is mathematically non-recoverable.
No Outbound Tracking: Astronomical math is computed locally within the isolated V8 runtime; zero external requests are made to third-party tracking APIs.
Fail-Open Architecture: Host middleware is designed to fail open; network issues or latency spikes will never block primary AI conversation streams.
Full Disclosure Process: See SECURITY.md for supported versions, SLA, and private reporting.

📄 Governance, Citations & Community

License: MIT License
Citation: CITATION.cff
Maintainers: MAINTAINERS.md
Governance: GOVERNANCE.md
Product Roadmap: ROADMAP.md
Agent Guidelines: AGENTS.md
Contributing: CONTRIBUTING.md
Code of Conduct: CODE_OF_CONDUCT.md
Discussions: GitHub Discussions

Made with precision for the global Muslim developer community.