🕌 Muslim Prayer Reminder MCP

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:

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

2. Connect via Remote Streamable HTTP (Cloudflare Workers)

{
  "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:

---

🏛️ System Architecture

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:

/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:

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:

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

Or inside an interactive Copilot CLI session:

/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:

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

---

Claude Desktop

Add to your claude_desktop_config.json:

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

---

VS Code & Cline

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

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

---

Windsurf & Devin

Add to mcp_config.json:

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

---

Gemini CLI

Connect directly using the live edge endpoint:

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

---

Pi Agent Harness

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

---

OpenCode

Add to your opencode.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

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:

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:

npm test

▶ 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