What is the HalalScreener MCP?

An MCP server that lets AI agents like Claude, Cursor, and ChatGPT screen stocks for Shariah (halal) compliance under AAOIFI Standard No. 21, with audited verdicts, purification, and an AI Scholar.

Is the HalalScreener MCP free?

Yes. A free tier gives 3 verdict-only screens (lifetime total). Premium ($16.99/mo) unlocks unlimited screening, full ratios, the reasoning trail, purification amounts, and the AI Scholar.

Is an MCP verdict a fatwa?

No. Verdicts are informational, algorithmic applications of AAOIFI Standard No. 21: batch-screened, never an autonomous trade gate, and assume a human in the loop. Consult a qualified scholar.

How do I connect it to Claude or Cursor?

Add `npx -y halalscreener-mcp` with your HALALSCREENER_API_KEY, or point a remote MCP client at https://halalscreener.app/api/mcp/mcp with an Authorization: Bearer key.

Model Context Protocol

The halal compliance layer for your AI agent

Connect Claude, Cursor, or ChatGPT to HalalScreener and let your agent screen stocks for Shariah compliance under AAOIFI Standard No. 21, with audited, explainable verdicts, purification, and the AI Scholar. Read-only and informational, never a trade gate.

Add to Cursor (1-click)Get an API key Read the docs

Built for trust, not blind automation

Every verdict carries a methodology version, the ratios used, a freshness flag, a reproducible audit hash, and a "consult a scholar" flag. Verdicts are batch-screened (not real-time), not a fatwa, and assume a human in the loop. We never tell your agent to buy or sell.

Connect in 60 seconds

1Generate an API key on the developers page. It starts with hs_live_ and is shown once, so copy it right away.
2Copy the config below into your client's MCP file (paths listed under each option).
3Replace hs_live_your_key with your real key. The placeholder on its own returns 401 Unauthorized.
4Restart the client. Ask it "Is AAPL halal?" to confirm the server is live.

Option A: Local (Claude Desktop / Cursor)

Paste this into the file for your client, then restart it:

Claude Desktop: Settings → Developer → Edit Config, which opens claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\)
Cursor: Settings → MCP → Add new global MCP server, which opens ~/.cursor/mcp.json (or .cursor/mcp.json inside a project)

{
  "mcpServers": {
    "halalscreener": {
      "command": "npx",
      "args": ["-y", "halalscreener-mcp"],
      "env": { "HALALSCREENER_API_KEY": "hs_live_your_key" }
    }
  }
}

Used "Add to Cursor (1-click)" above? It installs the server with a placeholder key. Open Cursor Settings → MCP → halalscreener and paste your real key into HALALSCREENER_API_KEY.

Option B: Remote (Streamable HTTP)

For clients that support remote MCP servers (ChatGPT, Claude.ai connectors), point them at the hosted endpoint with your key as a Bearer token:

https://halalscreener.app/api/mcp/mcp
Authorization: Bearer hs_live_your_key

Tools

Tool	Tier	What it does
screen_stock	Free	AAOIFI verdict + grade + reproducible audit hash for a symbol.
screen_portfolio	Free	Per-symbol verdicts plus a portfolio compliance summary.
get_stock_detail	Premium	Full financial + qualitative/quantitative breakdown.
explain_verdict	Premium	The auditable 'why' behind a verdict: the gate that drove it.
calculate_purification	Premium	Impure income to donate, per AAOIFI Standard No. 21.
ask_scholar	Premium	Conversational multi-madhab Islamic-finance Q&A (AI Scholar).
check_compliance_changes	Premium	Portfolio drift monitor: which holdings changed status since a date.
compliance_history	Premium	A stock's AAOIFI verdict timeline over time.

Free tier: 3 verdict-only screens total. Premium ($16.99/mo) unlocks unlimited screening, full verdicts, the reasoning trail, purification, and the AI Scholar.

Make your agent halal-aware

Generate a key, paste the config, and your AI can screen any US-listed stock, ETF, or major crypto for Shariah compliance, with the receipts.

Get your API key