Content
# Halal Terminal MCP — Shariah-compliant stock & ETF screening for AI agents
> [English](README.md) | [العربية](README.ar.md) | [Bahasa Indonesia](README.id.md) | [Melayu](README.ms.md) | [اردو](README.ur.md) | [Français](README.fr.md)
 _live badge from the API, embed one for any symbol_
[](https://www.npmjs.com/package/@halalterminal/mcp)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://halalterminal.com)
The official **Model Context Protocol** server for [Halal Terminal](https://halalterminal.com). 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
1. **Get a free API key** — email-only signup at [api.halalterminal.com](https://api.halalterminal.com). No credit card. Key arrives in your inbox in seconds.
2. **Connect your client** — one-liners below (or see [CONNECT.md](CONNECT.md) for Cursor, Windsurf, Cline, and others).
3. **Ask your first question** — `"Is AAPL halal?"` → the agent calls `screen_stock` and returns verdicts across all 5 methodologies.
## Install
```bash
# Recommended — no install needed
npx -y @halalterminal/mcp
# Or pin globally
npm install -g @halalterminal/mcp
```
### Claude Desktop
```json
{
"mcpServers": {
"halalterminal": {
"command": "npx",
"args": ["-y", "@halalterminal/mcp"],
"env": { "HALALTERMINAL_API_KEY": "ht_yourkey" }
}
}
}
```
### Claude Code
```bash
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](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](TOOLS.md). End-to-end prompt walkthroughs in [EXAMPLES.md](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 |
Sign up: [api.halalterminal.com](https://api.halalterminal.com) · Pricing: [halalterminal.com/pricing](https://halalterminal.com/pricing)
## 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](https://github.com/goww7/halalterminal-mcp/issues) or email yassir@halalterminal.com.
## Learn more
- [API reference](https://api.halalterminal.com/api-reference)
- [Building an Islamic finance MCP server](https://www.halalterminal.com/blog/posts/islamic-finance-mcp-server)
- [What is Islamic finance?](https://www.halalterminal.com/research/what-is-islamic-finance)
- [Sukuk screening guide](https://www.halalterminal.com/research/sukuk-screening)
- [Is my stock halal? Screener](https://www.halalterminal.com/stocks)
## Part of the Halal Terminal ecosystem
[Website](https://www.halalterminal.com) · [API](https://api.halalterminal.com/api-reference) · [Python SDK](https://github.com/goww7/halalterminal-sdk-python) · [JS SDK](https://github.com/goww7/halalterminal-sdk-js) · [Claude plugin](https://github.com/goww7/halalterminal-claude-skills) · [Discord bot](https://github.com/goww7/halal-discord-bot) · [TradingView indicator](https://github.com/goww7/halal-pine) · [Portfolio tracker](https://github.com/goww7/halal-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**](https://github.com/goww7/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**](https://github.com/goww7/yassir-oss) | Open-source ReAct agent for halal finance research — CLI + web UI; supports OpenAI / Anthropic / local LLMs. | Apache-2.0 |
| [**halal-discord-bot**](https://github.com/goww7/halal-discord-bot) | Discord bot — `/halal AAPL`, `/portfolio`, `/trending` slash commands. | MIT |
| [**halal-portfolio-tracker**](https://github.com/goww7/halal-portfolio-tracker) | Next.js 14 app — enter holdings, get per-stock compliance + portfolio halal % + purification owed. One-click Vercel deploy. | MIT |
| [**halal-pine**](https://github.com/goww7/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](LICENSE).
"Halal Terminal", "HalalTerminal", and the Halal Terminal logo are reserved trademarks — see [TRADEMARKS.md](TRADEMARKS.md).
## Legal
- [Legal & Disclaimer](https://halalterminal.com/legal) — educational-research framing, investment disclaimer, Shariah compliance notice, liability limits, jurisdiction notices
- [Privacy Policy](https://halalterminal.com/privacy)
- [Cookie Policy](https://halalterminal.com/cookies)
## Support
- Contact: yassir@halalterminal.com
- Dashboard: [api.halalterminal.com/dashboard](https://api.halalterminal.com/dashboard)
- API docs: [api.halalterminal.com/docs](https://api.halalterminal.com/docs) (Swagger) · [api.halalterminal.com/redoc](https://api.halalterminal.com/redoc) (ReDoc)
---
Powered by Halal Terminal — [halalterminal.com](https://halalterminal.com)
---
Part of the [Halal Terminal open ecosystem](https://github.com/goww7/awesome-islamic-finance):
[API](https://api.halalterminal.com) · [MCP server](https://github.com/goww7/halalterminal-mcp) · [Python SDK](https://github.com/goww7/halalterminal-sdk-python) · [JS SDK](https://github.com/goww7/halalterminal-sdk-js) · [Datasets](https://github.com/goww7/sp500-shariah-compliance) · [Awesome Islamic Finance](https://github.com/goww7/awesome-islamic-finance)
