{
  "markdown": "# Halal Terminal MCP — Shariah-compliant stock & ETF screening for AI agents\n\n> [English](README.md) | [العربية](README.ar.md) | [Bahasa Indonesia](README.id.md) | [Melayu](README.ms.md) | [اردو](README.ur.md) | [Français](README.fr.md)\n\n![AAPL halal status](https://api.halalterminal.com/api/badge/AAPL.svg) _live badge from the API, embed one for any symbol_\n\n[![npm version](https://img.shields.io/npm/v/@halalterminal/mcp.svg)](https://www.npmjs.com/package/@halalterminal/mcp)\n[![Apache 2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n[![MCP](https://img.shields.io/badge/protocol-MCP-purple)](https://modelcontextprotocol.io)\n[![Powered by Halal Terminal](https://img.shields.io/badge/powered%20by-Halal%20Terminal-1f6feb)](https://halalterminal.com)\n\nThe 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.\n\n> *\"Is AAPL halal?\"* · *\"Audit my portfolio: AAPL 30%, MSFT 20%, JNJ 50%\"* · *\"Calculate zakat on my holdings.\"*\n\n## Quick start\n\n1. **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.\n2. **Connect your client** — one-liners below (or see [CONNECT.md](CONNECT.md) for Cursor, Windsurf, Cline, and others).\n3. **Ask your first question** — `\"Is AAPL halal?\"` → the agent calls `screen_stock` and returns verdicts across all 5 methodologies.\n\n## Install\n\n```bash\n# Recommended — no install needed\nnpx -y @halalterminal/mcp\n\n# Or pin globally\nnpm install -g @halalterminal/mcp\n```\n\n### Claude Desktop\n\n```json\n{\n  \"mcpServers\": {\n    \"halalterminal\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@halalterminal/mcp\"],\n      \"env\": { \"HALALTERMINAL_API_KEY\": \"ht_yourkey\" }\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add --transport sse halalterminal \\\n  https://mcp.halalterminal.com/sse \\\n  --header \"X-API-Key: ht_yourkey\"\n```\n\n### Cursor / Windsurf / direct SSE\n\n```\nhttps://mcp.halalterminal.com/sse?api_key=ht_yourkey\n```\n\nFull setup guide for all clients: [CONNECT.md](CONNECT.md).\n\n## What you get — 22 tools across 8 categories\n\n| Category | Tools |\n|---|---|\n| **Screening** | `screen_stock`, `screen_etf`, `bulk_screen`, `get_screening_result`, `get_all_screening_results` |\n| **Market data** | `get_quote`, `get_stock_info`, `get_price_history`, `get_trending_stocks`, `search_stocks` |\n| **ETF analysis** | `get_etf_info`, `etf_purification`, `compare_etfs` |\n| **Portfolio & watchlist** | `scan_portfolio`, `manage_watchlist` |\n| **Comparison** | `compare_stocks` |\n| **Income & zakat** | `get_dividends`, `calculate_zakat` |\n| **News & filings** | `get_news`, `get_sec_filings` |\n| **Reports & education** | `generate_report`, `islamic_finance_education` |\n\nFull input/output reference in [TOOLS.md](TOOLS.md). End-to-end prompt walkthroughs in [EXAMPLES.md](EXAMPLES.md).\n\n## Why Halal Terminal\n\n- **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.\n- **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.\n- **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.\n- **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.\n- **Free tier, no credit card.** Email signup → key in your inbox in seconds → ~5–10 full screens per month at no cost.\n\n## Endpoint & transport\n\n```\nSSE: https://mcp.halalterminal.com/sse\nAuth: X-API-Key: <your_key>   (or ?api_key=<your_key>)\n```\n\nTransports supported: **SSE** (recommended), **stdio** (via this `@halalterminal/mcp` bridge for clients that need it).\n\n## Plans & quotas\n\nThe Halal Terminal API is **token-metered**, not request-metered.\n\n| Plan | Monthly tokens | Price | Notes |\n|---|---|---|---|\n| **Free** | 50 | $0 | ~5–10 full screenings · email signup, no credit card |\n| **Starter** | 2,500 | $19 | Individual investors |\n| **Pro** | 15,000 | $49 | Webhooks, bulk priority |\n| **Enterprise** | Unlimited | $199+ | Custom methodologies, SLA |\n\nSign up: [api.halalterminal.com](https://api.halalterminal.com) · Pricing: [halalterminal.com/pricing](https://halalterminal.com/pricing)\n\n## What this MCP server is NOT\n\n- **Not a fatwa.** Every verdict is a methodology-based screening. Consult a qualified scholar for personal rulings.\n- **Not a trading platform.** No broker integrations, no order execution.\n- **Not a real-time alert system.** Request-response only in v1; webhook-driven alerts are on the Pro+ roadmap.\n- **English-only in v1.** Arabic + French rendering is on the roadmap.\n\n## FAQ\n\n### Is this MCP server free to use?\n\nYes. 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.\n\n### Which AI clients does it work with?\n\nAny 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.\n\n### How is \"halal\" determined?\n\nEach 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.\n\n### What is dividend purification?\n\nWhen 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.\n\n### Can it screen ETFs?\n\nYes — `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).\n\n### Can I screen an entire index at once?\n\nYes — `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.\n\n### Does it support webhooks for compliance changes?\n\nWebhooks are a Pro-plan feature on the API roadmap; v1 of this MCP is request-response only.\n\n### Where do I report bugs or request tools?\n\n[github.com/goww7/halalterminal-mcp/issues](https://github.com/goww7/halalterminal-mcp/issues) or email yassir@halalterminal.com.\n\n## Learn more\n\n- [API reference](https://api.halalterminal.com/api-reference)\n- [Building an Islamic finance MCP server](https://www.halalterminal.com/blog/posts/islamic-finance-mcp-server)\n- [What is Islamic finance?](https://www.halalterminal.com/research/what-is-islamic-finance)\n- [Sukuk screening guide](https://www.halalterminal.com/research/sukuk-screening)\n- [Is my stock halal? Screener](https://www.halalterminal.com/stocks)\n\n## Part of the Halal Terminal ecosystem\n\n[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)\n\n## Related projects (sibling OSS)\n\nOpen-source tools that share the same Halal Terminal API — different surfaces, same data:\n\n| Project | What it is | License |\n|---|---|---|\n| [**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 |\n| [**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 |\n| [**halal-discord-bot**](https://github.com/goww7/halal-discord-bot) | Discord bot — `/halal AAPL`, `/portfolio`, `/trending` slash commands. | MIT |\n| [**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 |\n| [**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 |\n\n## License & trademarks\n\nApache-2.0 — see [LICENSE](LICENSE).\n\n\"Halal Terminal\", \"HalalTerminal\", and the Halal Terminal logo are reserved trademarks — see [TRADEMARKS.md](TRADEMARKS.md).\n\n## Legal\n\n- [Legal & Disclaimer](https://halalterminal.com/legal) — educational-research framing, investment disclaimer, Shariah compliance notice, liability limits, jurisdiction notices\n- [Privacy Policy](https://halalterminal.com/privacy)\n- [Cookie Policy](https://halalterminal.com/cookies)\n\n## Support\n\n- Contact: yassir@halalterminal.com\n- Dashboard: [api.halalterminal.com/dashboard](https://api.halalterminal.com/dashboard)\n- API docs: [api.halalterminal.com/docs](https://api.halalterminal.com/docs) (Swagger) · [api.halalterminal.com/redoc](https://api.halalterminal.com/redoc) (ReDoc)\n\n---\n\nPowered by Halal Terminal — [halalterminal.com](https://halalterminal.com)\n\n\n---\n\nPart of the [Halal Terminal open ecosystem](https://github.com/goww7/awesome-islamic-finance):\n[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)\n",
  "bytes": 11080,
  "sha": "d7d298dcbee481bbd61c5a0e75c6233d54058bbbf5a0a75d444e825015221055",
  "repo_slug": "goww7/halalterminal-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_halalterminal_mcp_10286771/readme"
}