islamqa-org-mcp

Claude, Codex 및 기타 모든 MCP 클라이언트에 출처가 있는 약 98,000개의 파트와(fatwa)에 대한 접근 권한을 제공합니다.

IslamQA.org용 MCP 서버로, 4대 수니파 마드하브(madhahib)에 걸친 47개 독립 다룰 이프타(darul ifta) 기관의 답변을 집계합니다.

웹사이트 · 설치 · ChatGPT · 도구 · 작동 방식 · 예절

왜 필요한가

언어 모델에게 피끄(fiqh) 질문을 하면 훈련 데이터의 모호한 혼합에서 출처도, 마드하브도, 검증 방법도 없이 답변합니다. 이런 종류의 질문에는 그런 방식이 맞지 않습니다.

이 서버는 기본값을 바꿉니다. 어시스턴트가 학술 답변의 실제 아카이브를 검색하고, 무프티(mufti), 마드하브, 기관, 그리고 열어볼 수 있는 URL과 함께 하나를 인용합니다. 학파들이 의견을 달리할 때, 하나의 입장이 그 이슬람 판결인 것처럼 제시되는 대신 의견이 다르다는 사실을 볼 수 있습니다.

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

설치

클론도, 수동 설정도 필요 없습니다. 이미 가지고 있는 러너(runner)를 선택하세요.

uv 사용 시 (권장 — 실제로 서버를 실행하는 도구입니다):

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

npx 사용 시, Node가 더 익숙하다면:

npx -y islamqa-mcp

npm 패키지는 얇은 래퍼입니다 — uv에 작업을 넘기며, uv가 격리된 캐시 환경에서 Python 서버를 가져와 실행합니다. 여전히 uv가 설치되어 있어야 합니다. 래퍼가 없을 경우 설치 방법을 알려줍니다.

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

claude_desktop_config.json에 추가하세요 — 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

~/.codex/config.toml에 추가하세요:

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

클라이언트를 다시 시작하세요. 첫 검색은 로컬 인덱스를 구축합니다(약 1분, 약 22회 요청). 이후의 모든 것은 즉시 처리됩니다.

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

그런 다음 클라이언트를 uv --directory /absolute/path/to/islamqa-org-mcp run islamqa-mcp로 지정하세요.

ChatGPT

ChatGPT는 위의 클라이언트들과 다릅니다. 로컬 프로세스를 실행할 수 없으므로 서버가 공개 HTTPS URL에서 호스팅되어야 합니다. 두 가지가 필요합니다.

1. stdio 대신 HTTP로 실행하세요.

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

ChatGPT가 필요로 하는 엔드포인트는 https://your-host/mcp입니다.

2. 이 모드에서는 search와 fetch를 노출합니다. ChatGPT는 개발자 모드(Developer Mode)를 켜지 않은 한 정확히 그 이름의 도구가 없는 커넥터를 거부하며, Deep Research는 항상 그 두 가지만 호출합니다. 따라서 HTTP로 실행할 때 서버는 OpenAI가 요구하는 형태로 search_fatwas / get_fatwa 위에 어댑터로 이를 추가합니다 — search는 결과당 {id, title, url}을 반환하고, fetch는 {id, title, text, url, metadata}를 반환합니다. 모든 결과에는 실제 islamqa.org URL이 포함되어 ChatGPT가 올바른 인용을 렌더링합니다.

이들은 의도적으로 stdio에는 등록되지 않습니다. Claude와 Codex는 더 풍부한 search_fatwas를 받으며, 더 약한 별칭을 추가하면 모델이 더 나쁜 도구를 사용하게 될 뿐입니다.

배포 없이 시도하기

로컬에서 실행하고 터널을 연결하세요 — ChatGPT 커넥터 대화상자의 Tunnel 토글이 바로 이 용도입니다:

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

그런 다음 ChatGPT에서: Settings → Apps → Advanced → Developer mode, https://<your-tunnel>/mcp를 가리키는 커넥터를 추가하고 인증은 None으로 설정하세요.

제대로 호스팅하기

Dockerfile이 포함되어 있으며 Render, Railway, Fly.io 또는 Cloud Run에서 작동합니다:

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

이미지 빌드 시점에 URL 인덱스를 구축합니다. 이는 중요합니다. 인덱스는 islamqa.org에 약 22회의 요청이 필요하며, 이미지에 포함하면 릴리스당 한 번만 발생하고 모든 복제본의 모든 콜드 스타트마다 발생하지 않습니다. 그렇게 하지 않으면 자동 확장되는 무료 티어가 하루 종일 사이트맵을 다시 크롤링하게 됩니다. 또한 첫 사용자 검색이 즉시 처리됩니다.

공개적으로 노출하기 전에: 인증이 없는 커넥터는 URL을 찾는 누구에게나 열려 있으며, 그들이 보내는 모든 요청은 서버 이름으로 islamqa.org에 대한 요청입니다. 본인만 사용하는 것이 아니라면 OAuth 또는 인증 프록시 뒤에 두고, 속도 제한은 현재 상태로 유지하세요.

스킬

MCP 서버는 모델에게 도구를 제공합니다. 도구를 잘 사용하는 방법은 알려주지 않습니다 — 그리고 피끄에서는 무엇을보다 어떻게가 더 중요합니다.

skills/islamqa-fatwa는 서버와 함께 제공되는 Claude 스킬입니다. 어시스턴트가 다음을 수행하도록 만듭니다:

• 답변 전에 따르는 마드하브를 묻습니다 — 또는 따르는 마드하브가 없으면 네 학파의 입장을 나란히 제시합니다

• 검색하지 않은 판결을 절대 내리지 않습니다. 지어낸 하디스, 어렴풋이 기억나는 "하나피 학파의 견해는…", 조작된 아랍어 인용이 없습니다. 아카이브에 내용이 없으면 그 자리를 채우는 대신 그렇게 말합니다

• 전통의 실제 범주를 사용합니다. 모든 것을 할랄/하람으로 평탄화하지 않고 하나피 7분법을 포함하여 makrūh taḥrīmī가 조용히 "싫어함"으로 격하되거나 "하람"으로 승격되지 않도록 합니다

• 커버리지가 부족할 때 말합니다. 아카이브는 하나피 중심입니다. 말리키 답변이 없으면 추론하는 대신 그 사실을 보고합니다

• 이혼, 상속, 양육권 등 검색 인덱스가 아닌 사람이 필요한 문제는 전문가에게 회부합니다

전역으로 설치하세요:

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

질문이 판결 질문으로 판명되면 자동으로 활성화됩니다.

도구

HTTP에서는 ChatGPT 호환성을 위해 search와 fetch가 추가됩니다 — ChatGPT 참조.

모든 답변은 출처 표시와 함께 반환되며, 모델에게 URL을 인용하고 판결을 보편적인 것이 아닌 한 무프티의 입장으로 취급하라는 메모가 포함됩니다.

명령줄

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

작동 방식

IslamQA.org는 REST API가 비활성화된 WordPress를 실행하므로 호출할 JSON 엔드포인트가 없습니다. 게시하는 것은 완전한 사이트맵과 서버 렌더링 페이지 — 일반 독자나 검색 엔진 크롤러가 보는 것과 동일한 공개 페이지입니다.

서버는 두 계층으로 작동합니다:

인덱스. 사이트맵을 한 번 훑어(~22회 요청) 모든 답변 URL을 ID, 마드하브, 발행 출처, 슬러그에서 파생된 제목과 함께 기록합니다. 약 98,000개의 답변이 몇 메가바이트와 약 1분이면 충분하며, 이후 검색은 로컬에서 즉시 처리됩니다.

캐시. 답변을 읽으면 해당 페이지 하나를 가져와 파싱한 후 저장합니다. 검색은 두 계층 모두에 대해 SQLite FTS5 인덱스에서 실행되므로, 답변은 제목으로 즉시 찾을 수 있고 누군가 읽은 후에는 전체 텍스트로도 찾을 수 있습니다 — 사용할수록 아카이브가 더 검색 가능해집니다.

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

답변이 수년에 걸쳐 47개 다른 사이트에서 가져와졌기 때문에 페이지는 세 가지 템플릿 형태로 제공되며, 세 가지 모두 처리됩니다: 현대식 .ai-question / .ai-answer-content 래퍼; 명시적인 Question: / Answer: 레이블이 있는 일반 문단; 레이블이 전혀 없는 일반 문단. 불필요한 Q: 접두사와 끝의 "Original Source Link" 텍스트는 제거되고, 고전 문헌을 인용하는 아랍어 각주는 별도의 citations 필드로 분리되어 답변이 그 뒤의 증거를 잃지 않고 깔끔하게 읽힙니다.

islamqa.org에 API가 있나요?

공개 JSON API는 없습니다. 사이트는 WordPress를 실행하지만 REST API는 사이트 전체에서 꺼져 있습니다. 2026년 8월 프로브 결과:

사이트 내 검색 상자는 ElasticPress에 의해 클라이언트 측에서 렌더링되므로 그 결과도 HTML에 없습니다 — 그래서 이 서버는 사이트 검색을 프록시하는 대신 자체 인덱스를 구축합니다.

기계가 읽을 수 있고 공개된 것:

이 서버는 사이트맵과 답변 페이지를 사용합니다. RSS 피드는 검색이 필요 없고 새 답변만 원하는 경우 가벼운 옵션입니다 — 인덱스와 스크래핑이 필요 없습니다:

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

답변 URL은 구조화되어 있어 어떤 답변이든 직접 주소를 지정할 수 있습니다:

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

islamqa.org가 REST API를 활성화하면 이 서버는 해당 API로 전환해야 합니다 — 복귀를 발견하면 이슈를 열어주세요.

구성

모두 선택 사항이며 환경 변수로 설정합니다:

예절 (adab)

이 서비스는 기부로 운영되는 무료 서비스를 읽으므로 좋은 손님이 되도록 구축되었습니다:

• 초당 요청 1회, 전역적으로 직렬화됨 — 동시 도구 호출이 버스트로 확산될 수 없음.

• 적극적으로 캐싱함. 파트와는 게시되면 사실상 변경되지 않으므로, 페이지는 한 번 가져와 90일 동안 재사용됨.

• 요청된 것만 가져옴. 대량 수집은 사이트맵을 읽지, 100,000개의 답변 페이지를 읽지 않음. 여기에는 크롤러가 없음.

• 자신을 식별함. 이 저장소를 가리키는 실제 User-Agent를 사용함.

• 단일 호스트에 고정됨. 모든 URL은 소켓이 열리기 전에 허용 목록으로 검사되므로, 모델의 어떤 인수도 이를 공개 프록시로 만들 수 없음.

• 모든 출처를 명시함. 발행 기관, 이름이 명시된 경우 무프티, 그리고 다룰 이프타 자체 사본에 대한 링크가 모든 답변과 함께 전달됨.

islamqa.org를 운영 중이고 여기서 무엇이든 변경을 원한다면 — 속도 제한, User-Agent, 또는 도구의 존재 자체 — 이슈를 열어 주시면 처리하겠습니다.

사용에 관하여. 이들은 자격을 갖춘 무프티의 답변이지만, 파트와는 특정 상황에 있는 특정 개인에게 주어집니다. 검색 결과는 귀하의 상황에 대한 판결이 아니며, 이를 전달하는 언어 모델은 학자가 아닙니다. 중대한 사안에 대해서는 자격을 갖춘 사람에게 직접 문의하십시오.

개발

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

파서 테스트는 실제 페이지의 축소된 사본을 대상으로 실행됩니다. islamqa.org가 템플릿을 변경하면 테스트가 크게 실패하는데, 이는 의도적입니다. 조용한 파싱 회귀는 모델에게 빈 답변을 조용히 전달할 수 있기 때문입니다.

라이선스

MIT — LICENSE 참조.

라이선스는 이 소프트웨어에만 적용됩니다. 파트와는 이를 발행한 학자와 기관의 소유입니다. 이 도구는 공개 페이지를 읽고 링크를 제공할 뿐, 아카이브를 재배포하지 않습니다.