Halal Terminal MCP — Shariah-compliant stock & ETF screening for AI agents

English | العربية | Bahasa Indonesia | Melayu | اردو | Français

!AAPL halal status _live badge from the API, embed one for any symbol_

![npm version](https://www.npmjs.com/package/@halalterminal/mcp) ![Apache 2.0](LICENSE) ![MCP](https://modelcontextprotocol.io) ![Powered by Halal Terminal](https://halalterminal.com)

The official Model Context Protocol server for Halal Terminal. Give your AI agent 22 tools to answer Islamic-finance questions: screen any stock or ETF across 5 methodologies (AAOIFI, DJIM, FTSE, MSCI, S&P), audit portfolios, calculate zakat and dividend purification, and pull live market data, news and SEC filings. Works inside Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, Zed, Goose, and any other MCP client.

"Is AAPL halal?" · "Audit my portfolio: AAPL 30%, MSFT 20%, JNJ 50%" · "Calculate zakat on my holdings."

Quick start

Get a free API key — email-only signup at api.halalterminal.com. No credit card. Key arrives in your inbox in seconds.
Connect your client — one-liners below (or see CONNECT.md for Cursor, Windsurf, Cline, and others).
Ask your first question — "Is AAPL halal?" → the agent calls screen_stock and returns verdicts across all 5 methodologies.

Install

# Recommended — no install needed
npx -y @halalterminal/mcp

# Or pin globally
npm install -g @halalterminal/mcp

Claude Desktop

{
  "mcpServers": {
    "halalterminal": {
      "command": "npx",
      "args": ["-y", "@halalterminal/mcp"],
      "env": { "HALALTERMINAL_API_KEY": "ht_yourkey" }
    }
  }
}

Claude Code

claude mcp add --transport sse halalterminal \
  https://mcp.halalterminal.com/sse \
  --header "X-API-Key: ht_yourkey"

Cursor / Windsurf / direct SSE

https://mcp.halalterminal.com/sse?api_key=ht_yourkey

Full setup guide for all clients: CONNECT.md.

What you get — 22 tools across 8 categories

| Category | Tools | |---|---| | Screening | screen_stock, screen_etf, bulk_screen, get_screening_result, get_all_screening_results | | Market data | get_quote, get_stock_info, get_price_history, get_trending_stocks, search_stocks | | ETF analysis | get_etf_info, etf_purification, compare_etfs | | Portfolio & watchlist | scan_portfolio, manage_watchlist | | Comparison | compare_stocks | | Income & zakat | get_dividends, calculate_zakat | | News & filings | get_news, get_sec_filings | | Reports & education | generate_report, islamic_finance_education |

Full input/output reference in TOOLS.md. End-to-end prompt walkthroughs in EXAMPLES.md.

Why Halal Terminal

5 methodologies, one tool. AAOIFI, DJIM, FTSE Shariah, MSCI Islamic, and S&P Shariah — each with distinct business-activity rules and financial-ratio thresholds — surfaced side-by-side per stock so users pick the standard they follow.
Holdings-level ETF screening. Every constituent is screened, weighted, and aggregated into an overall verdict plus a per-dollar purification rate. Covers SPY, QQQ, VTI, ISDU, SPUS, HLAL, and 8,000+ ETFs.
Zakat & purification, computed. 2.5% zakat against a live nisab threshold; per-dividend impure-income calculation based on the issuer's non-compliant revenue ratio.
Bulk index screens. Trigger-and-poll runs on the S&P 500, NASDAQ-100, FTSE 100, and others; filter by methodology, sector, or compliant-only.
Free tier, no credit card. Email signup → key in your inbox in seconds → ~5–10 full screens per month at no cost.

Endpoint & transport

SSE: https://mcp.halalterminal.com/sse
Auth: X-API-Key: <your_key>   (or ?api_key=<your_key>)

Transports supported: SSE (recommended), stdio (via this @halalterminal/mcp bridge for clients that need it).

Plans & quotas

The Halal Terminal API is token-metered, not request-metered.

| Plan | Monthly tokens | Price | Notes | |---|---|---|---| | Free | 50 | $0 | ~5–10 full screenings · email signup, no credit card | | Starter | 2,500 | $19 | Individual investors | | Pro | 15,000 | $49 | Webhooks, bulk priority | | Enterprise | Unlimited | $199+ | Custom methodologies, SLA |

What this MCP server is NOT

Not a fatwa. Every verdict is a methodology-based screening. Consult a qualified scholar for personal rulings.
Not a trading platform. No broker integrations, no order execution.
Not a real-time alert system. Request-response only in v1; webhook-driven alerts are on the Pro+ roadmap.
English-only in v1. Arabic + French rendering is on the roadmap.

FAQ

Is this MCP server free to use?

Yes. The @halalterminal/mcp package is Apache-2.0 and free. The Halal Terminal API has a free tier (500 tokens / month, no credit card) that covers ~100 full stock screenings — enough to evaluate it before upgrading.

Which AI clients does it work with?

Any client that supports the Model Context Protocol over SSE or stdio — Claude Desktop, Claude Code, Cursor, Windsurf, Cline, Continue, Zed, Goose, and more. SSE is recommended; the @halalterminal/mcp package wraps it as stdio for clients that don't yet support SSE.

How is "halal" determined?

Each verdict applies the published rules of the chosen methodology — AAOIFI, Dow Jones Islamic Market (DJIM), FTSE Shariah, MSCI Islamic, and S&P Shariah. Two layers: (1) a business-activity screen (no alcohol, gambling, conventional finance, adult content, weapons, pork, …), then (2) financial-ratio thresholds (e.g. interest-bearing debt over market cap, illiquid assets, interest income share). The MCP exposes all five verdicts so the user — or scholar — can pick the standard they follow.

What is dividend purification?

When you hold a stock with a small share of non-compliant revenue, scholars require donating the non-compliant fraction of any dividend received. calculate_zakat(calculation_type="purification", …) and get_dividends(include_purification=True) compute that amount automatically.

Can it screen ETFs?

Yes — screen_etf walks every underlying holding, applies the methodology to each, and returns an overall verdict, compliant percentage, and aggregate purification rate. Sukuk ETFs are handled separately (asset-based methodologies).

Can I screen an entire index at once?

Yes — bulk_screen triggers an asynchronous run on indices like S&P 500, NASDAQ-100, FTSE 100, and lets you poll for status, filter results by methodology / sector / compliant-only, and diff two runs.

Does it support webhooks for compliance changes?

Webhooks are a Pro-plan feature on the API roadmap; v1 of this MCP is request-response only.

Where do I report bugs or request tools?

github.com/goww7/halalterminal-mcp/issues or email yassir@halalterminal.com.

Learn more

Part of the Halal Terminal ecosystem

Website · API · Python SDK · JS SDK · Claude plugin · Discord bot · TradingView indicator · Portfolio tracker

Related projects (sibling OSS)

Open-source tools that share the same Halal Terminal API — different surfaces, same data:

| Project | What it is | License | |---|---|---| | halalterminal-claude-skills | Claude Code plugin — curated skills, slash commands, and a portfolio-builder subagent on top of this MCP server. | Apache-2.0 | | yassir-oss | Open-source ReAct agent for halal finance research — CLI + web UI; supports OpenAI / Anthropic / local LLMs. | Apache-2.0 | | halal-discord-bot | Discord bot — /halal AAPL, /portfolio, /trending slash commands. | MIT | | halal-portfolio-tracker | Next.js 14 app — enter holdings, get per-stock compliance + portfolio halal % + purification owed. One-click Vercel deploy. | MIT | | halal-pine | TradingView Pine Script v5 indicator that overlays compliance status on charts. Refreshed daily from this API. | MIT |

License & trademarks

Apache-2.0 — see LICENSE.

"Halal Terminal", "HalalTerminal", and the Halal Terminal logo are reserved trademarks — see TRADEMARKS.md.

Legal

Legal & Disclaimer — educational-research framing, investment disclaimer, Shariah compliance notice, liability limits, jurisdiction notices
Privacy Policy
Cookie Policy

Support

Contact: yassir@halalterminal.com
Dashboard: api.halalterminal.com/dashboard
API docs: api.halalterminal.com/docs (Swagger) · api.halalterminal.com/redoc (ReDoc)

---

Part of the Halal Terminal open ecosystem: API · MCP server · Python SDK · JS SDK · Datasets · Awesome Islamic Finance

Halal Terminal