islamqa-org-mcp

Dale a Claude, Codex y cualquier otro cliente MCP acceso a ~98.000 fatwas con fuentes.

Un servidor MCP para IslamQA.org, que agrega respuestas de 47 instituciones darul ifta independientes de las cuatro madhahib suníes.

Sitio web · Instalación · ChatGPT · Herramientas · Cómo funciona · Etiqueta

Por qué

Hazle una pregunta de fiqh a un modelo de lenguaje y responderá a partir de una mezcla borrosa de datos de entrenamiento, sin fuente, sin madhhab y sin forma de verificarlo. Esa no es la forma adecuada para este tipo de pregunta.

Este servidor cambia el comportamiento por defecto. Tu asistente busca en un archivo real de respuestas académicas y cita una con el muftí, la madhhab, la institución y una URL que puedes abrir. Cuando las escuelas difieren, ves que difieren en lugar de recibir una sola posición presentada como la norma islámica.

You:  Can I wipe over ordinary cotton socks in wudu?

Claude: [searches IslamQA.org]

        The Hanafi position (Askimam.org, Mufti Ebrahim Desai) is that masah
        is only valid on socks with the characteristics of leather khuffayn —
        thick enough that water does not seep through, able to stand upright
        unaided, and durable over three to four miles of walking. Ordinary
        cotton socks do not qualify.
        https://islamqa.org/hanafi/askimam/127638/...

        Bin Bayyah (Maliki) notes the Hanbali school permits wiping over cloth
        socks, while the Maliki position restricts it to leather.
        https://islamqa.org/maliki/binbayyah/29891/...

Related MCP server: NexusNote MCP Server

Instalación

Sin clonar, sin configuración manual. Elige el ejecutor que ya tengas.

Con uv (recomendado: es lo que realmente ejecuta el servidor):

uvx --from git+https://github.com/RealYusufIsmail/islamqa-org-mcp islamqa-mcp

Con npx, si Node es lo que tienes a mano:

npx -y islamqa-mcp

El paquete npm es un envoltorio fino: delega en uv, que descarga y ejecuta el servidor Python en un entorno aislado en caché. Aun así necesitas uv instalado; el envoltorio te dice cómo si falta.

curl -LsSf https://astral.sh/uv/install.sh | sh    # macOS / Linux
brew install uv                                    # Homebrew
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"   # Windows

Claude Code

claude mcp add islamqa -- uvx --from git+https://github.com/RealYusufIsmail/islamqa-org-mcp islamqa-mcp

Claude Desktop

Añádelo a claude_desktop_config.json — en macOS, ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "islamqa": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/RealYusufIsmail/islamqa-org-mcp",
        "islamqa-mcp"
      ]
    }
  }
}

Codex

Añádelo a ~/.codex/config.toml:

[mcp_servers.islamqa]
command = "uvx"
args = ["--from", "git+https://github.com/RealYusufIsmail/islamqa-org-mcp", "islamqa-mcp"]

Reinicia el cliente. La primera búsqueda construye un índice local (aproximadamente un minuto, ~22 peticiones); todo lo demás es instantáneo.

git clone https://github.com/RealYusufIsmail/islamqa-org-mcp.git
cd islamqa-org-mcp && uv sync

Luego apunta el cliente a él con uv --directory /absolute/path/to/islamqa-org-mcp run islamqa-mcp.

ChatGPT

ChatGPT es diferente de los clientes anteriores: no puede lanzar un proceso local, así que necesita el servidor alojado en una URL HTTPS pública. De ello se derivan dos cosas.

1. Ejecútalo sobre HTTP en lugar de stdio.

islamqa-mcp --transport streamable-http --host 0.0.0.0 --port 8000

El endpoint que ChatGPT quiere es entonces https://your-host/mcp.

2. En este modo expone search y fetch. ChatGPT rechaza cualquier conector que no tenga herramientas con exactamente esos nombres a menos que hayas activado el Modo Desarrollador, y Deep Research solo llama a esas dos. Así que al ejecutarse sobre HTTP el servidor las añade como adaptadores sobre search_fatwas / get_fatwa, en la forma requerida por OpenAI — search devuelve {id, title, url} por resultado, fetch devuelve {id, title, text, url, metadata}. Cada resultado lleva una URL real de islamqa.org, así que ChatGPT genera citas correctas.

No están registradas para stdio, deliberadamente: Claude y Codex reciben el search_fatwas más completo, y añadir un alias más débil solo invitaría a usar el peor.

Probarlo sin desplegarlo

Ejecútalo localmente y apunta un túnel hacia él — para eso sirve el interruptor Tunnel en el diálogo de conectores de ChatGPT:

islamqa-mcp --transport streamable-http --port 8000
cloudflared tunnel --url http://localhost:8000     # or: ngrok http 8000

Luego en ChatGPT: Settings → Apps → Advanced → Developer mode, añade un conector que apunte a https://<your-tunnel>/mcp, autenticación None.

Alojarlo correctamente

Se incluye un Dockerfile que funciona en Render, Railway, Fly.io o Cloud Run:

docker build -t islamqa-mcp .
docker run -p 8000:8000 islamqa-mcp

Construye el índice de URLs en el momento de compilar la imagen, lo cual importa: el índice cuesta ~22 peticiones a islamqa.org, e incluirlo en la imagen significa que eso ocurre una vez por versión en lugar de en cada arranque en frío de cada réplica. Sin eso, un nivel gratuito con autoescalado volvería a rastrear el sitemap todo el día. También hace que la primera búsqueda del usuario sea instantánea.

Antes de exponerlo públicamente: un conector sin autenticación está abierto a cualquiera que encuentre la URL, y cada petición que hagan es una petición contra islamqa.org bajo el nombre de tu servidor. Ponlo detrás de OAuth o de un proxy de autenticación si no es solo para ti, y mantén el límite de peticiones donde está.

La habilidad

Un servidor MCP le da herramientas al modelo. No le dice cómo usarlas bien — y en fiqh, el cómo importa más que el qué.

skills/islamqa-fatwa es una habilidad de Claude que se distribuye junto con el servidor. Hace que el asistente:

• Pregunte qué madhhab sigues antes de responder — o presente las cuatro posiciones lado a lado si no sigues ninguna

• Nunca emita una norma que no haya recuperado. Nada de hadices inventados, ni recuerdos a medias de «la postura hanafí es…», ni citas árabes fabricadas. Si el archivo no tiene nada, lo dice en lugar de rellenar el vacío

• Use las categorías reales de la tradición en lugar de reducirlo todo a halal/haram — incluido el esquema séptuple hanafí, para que makrūh taḥrīmī no se rebaje silenciosamente a «desagradable» ni se eleve a «haram»

• Diga cuándo la cobertura es escasa. El archivo es mayoritariamente hanafí; si no hay respuesta malikí, lo informa en lugar de inferir una

• Derive los casos de divorcio, herencia, custodia y otros asuntos que necesitan a una persona en lugar de un índice de búsqueda

Instálala globalmente:

git clone https://github.com/RealYusufIsmail/islamqa-org-mcp.git /tmp/islamqa-mcp
cp -r /tmp/islamqa-mcp/skills/islamqa-fatwa ~/.claude/skills/

Se activa por sí sola cuando una pregunta resulta ser una cuestión de normas.

Herramientas

Sobre HTTP, se añaden search y fetch para compatibilidad con ChatGPT — ver ChatGPT.

Cada respuesta se devuelve con su atribución y una nota que recuerda al modelo que cite la URL y que trate la norma como la postura de un muftí, no como una universal.

Línea de comandos

Las mismas operaciones sin un cliente MCP:

uv run islamqa search "wiping over socks" --madhhab hanafi
uv run islamqa get https://islamqa.org/hanafi/askimam/127638/can-i-wipe-make-masah-over-the-new-socks/
uv run islamqa sources
uv run islamqa status

Cómo funciona

IslamQA.org usa WordPress con la API REST desactivada, así que no hay ningún endpoint JSON al que llamar. Lo que sí publica es un sitemap completo y páginas renderizadas en el servidor — las mismas páginas públicas que ve cualquier lector o rastreador de buscadores.

El servidor funciona en dos capas:

El índice. Una pasada por el sitemap (~22 peticiones) registra cada URL de respuesta junto con su ID, madhhab, fuente emisora y un título derivado del slug. Son ~98.000 respuestas por unos pocos megabytes y aproximadamente un minuto, y significa que la búsqueda es local e instantánea a partir de entonces.

La caché. Leer una respuesta descarga y analiza esa página, y luego la almacena. La búsqueda se ejecuta sobre un índice SQLite FTS5 de ambas capas, así que una respuesta se puede encontrar por título de inmediato y por su texto completo una vez que alguien la ha leído — el archivo se vuelve más buscable cuanto más lo usas.

sitemap ──► index (~98k URLs + titles) ──┐
                                         ├──► FTS5 (BM25) ──► search_fatwas
answer page ──► parse ──► cache (full) ──┘                    get_fatwa

Como las respuestas se importaron de 47 sitios diferentes a lo largo de muchos años, las páginas vienen en tres formatos de plantilla, y los tres se manejan: los envoltorios modernos .ai-question / .ai-answer-content; párrafos simples con etiquetas explícitas Question: / Answer:; y párrafos simples sin etiquetas. Los prefijos sueltos Q: y el texto final «Original Source Link» se eliminan, y las notas finales en árabe que citan textos clásicos se separan en un campo citations independiente, de modo que una respuesta se lee limpiamente sin perder la evidencia que la respalda.

¿Tiene islamqa.org una API?

No hay API JSON pública. El sitio usa WordPress, pero la API REST está desactivada en todo el sitio. Comprobado en agosto de 2026:

El cuadro de búsqueda del sitio se renderiza en el cliente con ElasticPress, así que sus resultados tampoco están en el HTML — por eso este servidor construye su propio índice en lugar de hacer de proxy de la búsqueda del sitio.

Lo que es legible por máquina y abierto:

Este servidor usa el sitemap y las páginas de respuestas. Los feeds RSS son una opción ligera si solo quieres respuestas nuevas y no necesitas búsqueda — no requieren índice ni scraping:

curl -s https://islamqa.org/hanafi/askimam/feed/

Las URLs de respuestas son estructuradas, así que puedes dirigirte a cualquier respuesta directamente:

https://islamqa.org/{madhhab}/{source}/{post_id}/{slug}/
                     hanafi   askimam  127638   can-i-wipe-make-masah-over-the-new-socks

Si islamqa.org activa alguna vez su API REST, este servidor debería cambiar a ella — abre un issue si notas que vuelve.

Configuración

Todo opcional, se establece como variables de entorno:

Etiqueta (adab)

Esto lee un servicio gratuito mantenido con donaciones, así que está construido para ser un buen invitado:

• Una solicitud por segundo, serializada globalmente: las llamadas de herramientas concurrentes no pueden expandirse en una ráfaga.

• Almacena en caché de forma agresiva. Las fatwas son efectivamente inmutables una vez publicadas, por lo que una página se obtiene una vez y se reutiliza durante 90 días.

• Obtiene solo lo que se le pide. La pasada masiva lee el sitemap, no 100 000 páginas de respuestas. Aquí no hay rastreador.

• Se identifica con un User-Agent real que apunta a este repositorio.

• Bloqueado a un solo host. Cada URL se verifica contra una lista de permitidos antes de abrir un socket, por lo que ningún argumento de un modelo puede convertir esto en un proxy abierto.

• Atribuye todo. La institución emisora, el muftí cuando se nombra, y un enlace a la copia propia del darul ifta viajan con cada respuesta.

Si mantienes islamqa.org y quieres que se cambie algo aquí — el límite de velocidad, el User-Agent o la existencia de la herramienta — por favor abre un issue y se abordará.

Sobre el uso de esto. Estas son respuestas de muftíes cualificados, pero una fatwa se da a una persona concreta en un contexto concreto. Un resultado de búsqueda no es un dictamen sobre tu situación, y un modelo de lenguaje que lo transmite no es un erudito. Para cualquier cosa de importancia, pregunta directamente a una persona cualificada.

Desarrollo

uv sync --extra dev
uv run pytest          # 81 tests, no network — runs against saved fixtures
uv run ruff check .
uv run mypy src/islamqa_mcp

Las pruebas del analizador se ejecutan contra copias recortadas de páginas reales. Si islamqa.org cambia su plantilla, fallan de forma ruidosa, lo cual es deliberado: una regresión silenciosa del análisis alimentaría silenciosamente respuestas vacías al modelo.

Licencia

MIT — ver LICENSE.

La licencia cubre solo este software. Las fatwas pertenecen a los eruditos e instituciones que las emitieron. Esta herramienta lee páginas públicas y enlaza de vuelta; no redistribuye el archivo.