Muslim Prayer Reminder MCP

Muslim Prayer Reminder MCP

Prayer times and reminders inside your AI workflow.
Get local prayer times, see what's next, and configure reminders in ChatGPT, Claude, Cursor, and other MCP clients.

Open in ChatGPT  ·  Documentation  ·  Quick Start  ·  Tools Catalog  ·  Watch the Demo

🕌 Launch week · 26 Oct – 1 Nov 2026: Muslim Prayer Reminder MCP is live on HalaLaunch
Watch the real 1080p demonstration · Try in ChatGPT

_{Actively maintained · Cloudflare Workers · Node.js 22/24 on Ubuntu and Windows
By Smart Creations · Maintained by Tareq Naji}

Local prayer times	Next prayer at a glance	Your setup, your choice
Location-aware timetables with 12 calculation methods.	Next-prayer countdowns and configurable reminder windows.	Connect to the hosted endpoint or run locally over stdio.

---

⚡ Quick Start

1. Run via NPX (Zero Installation)

Add to your Claude Desktop or Cursor 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

---

Analytics dashboard

/analytics displays daily, weekly, monthly, and selected-period active-user counts from a minimal SQLite Durable Object. It counts only identifiable ChatGPT tool users arriving through verified OpenAI egress IPs. It records no individual tool calls, handshakes, sessions, IPs, bot activity, or location details. The dashboard is public unless ANALYTICS_TOKEN or AUTH_TOKEN is configured.

• Protect it: set a Worker secret named ANALYTICS_TOKEN (Cloudflare dashboard, Worker, Settings, Variables and Secrets). Open /analytics and enter any username with the token as the password. /api/analytics also accepts Authorization: Bearer <token>.
• Data model: one row per distinct verified ChatGPT subject per UTC day, using a 64-bit truncated SHA-256 pseudonym with the public prefix mpr:v1:. No per-call analytics are retained; activity is kept for up to 180 days.
• Quota guardrails: 500 tracked distinct users per UTC day maximum; reporting has four fixed ranges (7/30/90/180 days) and at most one persisted snapshot per range each UTC day. When the cap is reached, additional user-days are not counted; prayer tools still work.
• Verification and limits: the subject and OpenAI IP-range checks are conservative signals, not proof of a human. Non-ChatGPT users, missing subject IDs, installs with no tool calls, and clients without verifiable provenance are not counted. No Worker-level scheme can reserve free quotas for the rest of the Cloudflare account.

📺 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

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["User coordinates + timezone or supported city"] --> Truncate["2-Decimal Sanitizer ~1.1km"]
        UserPref["Stored KV Preferences"] --> Resolver["Location Normalizer"]
        Headers["Verified end-user location headers"] --> Resolver
        Resolver --> Missing["No usable user location: location_required"]
        Truncate --> Resolver
    end

    GeoIP["Cloudflare network metadata"] --> Analytics["Operational analytics only"]

    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 Prompts and Resources

In addition to the five calculation and preference tools, compatible MCP clients can use two protocol-native, read-only learning features:

• Prompt: check_prayer_times_with_disclosure guides a client to obtain real prayer times using the tool, ask for missing location, and explain the calculation authority, reason for selection, and high-latitude adjustments.
• Resource: prayer://calculation-guide provides a short guide to location requirements, Asr conventions, twilight methods, and differences from local mosque timetables.

These features do not guess prayer times, read private preferences, or replace the calculation tools. They are available through the current hosted MCP endpoint. Older local npm versions may not provide the new prompt and resource until updated.

---

🛠️ 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	Temporary state write	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.
configure_prayer_preferences	Overwrites saved settings (destructiveHint: true)	Safe	Updates supplied preferences; switching fixed location can clear the previous location and timezone. Previous values are not retained for undo.
get_prayer_preferences	Read-Only	Safe	Reads saved public preference settings.

---

📐 Astronomical & Theological Rigor

Prayer calculations use astronomical models and configured regional methods; high-latitude substitutes and geographic heuristics are disclosed:

Sovereign Authority	Jurisdiction	Fajr Angle	Isha Angle / Interval	Default Asr Madhab
Umm al-Qura University	Saudi Arabia	18.5°	+90 min	Shafi / Standard
Egyptian General Survey	Egypt, Palestine, Levant	19.5°	17.5°	Shafi (configured Palestinian service 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
Configured Singapore method	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 mcp add --transport http muslim-prayer https://muslim-prayer-mcp.najetareqz.workers.dev/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 build -t muslim-prayer-mcp . then docker run --rm -i muslim-prayer-mcp (stdio)

---

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 this to .vscode/mcp.json using VS Code's servers format:

{
  "servers": {
    "muslim-prayer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "muslim-prayer-mcp"]
    }
  }
}

Cline settings use the mcpServers format shown in Quick Start.

---

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 mcp add --transport http muslim-prayer 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 build -t muslim-prayer-mcp .
docker run --rm -i muslim-prayer-mcp

---

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

---

Registries & ratings

---

📄 Governance, Ownership & Community

• Publisher & Organization: Smart Creations (OpenAI Organization ID: org-deULP4GGInsTcWmuaHWp3lxy)

• Lead Maintainer & Author: Tareq Naji (@tareq7)

• License: MIT License (Copyright © 2026 Smart Creations & Tareq Naji)

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

Verified location and calculation disclosures (v1.1.0)

Prayer tools accept a supported city, coordinates with timezone, or complete stored fixed settings. Missing location returns location_required; connector/IP geolocation and automatic Makkah fallback are not used. Explicit per-call inputs override fixed preferences. Host headers must represent the end user.

highLatitudeAdjustment discloses twilight substitutions and polar clamping; effectiveLatitude is present only for the +/-48-degree substitute and never echoes the original coordinate. calculationDetails reports location basis and regional, user, and method offsets. Invalid offsets that reverse prayer windows return invalid_calculation. Preferences expose fixedCoordinatesConfigured and fixedCityConfigured while redacting coordinates.

Analytics stores only pseudonymous verified ChatGPT user-days for up to 180 days. It does not store individual requests, session identifiers, errors, locations, or bot traffic. Snapshot reports refresh at most once per UTC day, and daily tracking stops after 500 distinct users to protect free quotas. Both dashboard aliases honor configured service authentication; without an analytics/service token, access is public. See the privacy policy for the precise trust boundaries.

Preference and display-time contracts

Explicit coordinates require timezone in the same request. Stored fixed-location timezones are never inherited for new explicit coordinates. calculationDetails.timezoneSource identifies explicit, city, stored, or host input; city timezones must match the canonical city zone or an IANA alias. Coordinate timezones are checked against an approximate offline lookup and nearby boundary cells; contradictory values return location_timezone_mismatch with expectedTimezone. Supply city or coordinates, never both. Geographic default authority follows the lookup, not the supplied display timezone.

Fixed mode requires a supported city or coordinates with timezone. New fixed coordinates require timezone in the same configuration request. Failed configuration updates save nothing. Switching to auto_travel preserves fixed location for reuse; clearFixedLocation:true removes city, coordinates and timezone and defaults to auto-travel, preserving unrelated preferences. Clear cannot accompany replacement location/timezone or incomplete fixed mode.

For identified users, prayer_window and exact_window emit once per prayer/date/mode; persistent emits throughout the prayer period. Locale changes and toggling reminders do not reset deduplication. Anonymous calls do not persist deduplication. expiresAtUtc retains its prayer-period meaning; prayerWindowExpiresAtUtc names the same boundary, and reminderWindowExpiresAtUtc describes eligibility, capped by the prayer boundary in exact mode. These fields appear when a reminder is emitted. Cross-region KV updates and deduplication remain best effort.

The Palestinian regional profile is a configured service heuristic using the Egyptian method with Dhuhr -1 and Maghrib +3 minute offsets. Its broad coordinate/timezone/country rules do not establish jurisdiction. Exact adoption of these parameters by the Palestinian ministry has not been verified from a primary source. Users can override method and offsets. Other regional choices are service defaults, not nationwide mandates. Method descriptions follow Adhan documentation.

The supported city vocabulary and aliases are advertised in each location input schema and generated skill. The service registers five tools only. Duplicate suffixed tools or old schemas in a connector require refreshing its registration; they are not separate server operations.

Timezone validation uses @photostructure/tz-lookup 11.7.0 (compact, approximate geographic data). Canonical IANA aliases are accepted; matching sampled UTC offsets is not sufficient, because DST transition dates can differ. Near boundaries, adjacent lookup zones within roughly 0.05 degrees are accepted and disclosed as nearby_boundary. This is not precise jurisdiction detection. Mathematical poles retain an explicit civil timezone choice; ocean cells require a matching nautical zone or nearby civil zone. New and updated fixed-city preferences store the canonical city timezone; contradictory supplied values are rejected. Legacy city records are presented canonically without rewriting other data on a read.

The caller must supply current city or coordinates/timezone in auto_travel mode; there is no automatic IP geolocation. Stored method preferences remain active while traveling. exact_window uses the saved duration or, when unset, the service default of 20 minutes unless an operator overrides it. Omitting the duration preserves existing preferences.