Yassir

Posted on Jul 31 • Originally published at halalterminal.com

Connect Claude to Shariah Stock Screening in 5 Minutes (MCP)

#ai #finance #mcp #claude

The Model Context Protocol (MCP) lets an AI client call external tools directly. Connect the Halal Terminal MCP server and your assistant can screen any stock or ETF for Shariah compliance in plain language, no copy-pasting tickers into a dashboard. This guide gets you from zero to a working setup in about five minutes.

What you get

Once connected, you can ask questions like "Is AAPL halal?" or "Audit this portfolio: AAPL, MSFT, GOOGL" straight inside Claude Desktop, Claude Code, Cursor, or any other MCP client (Windsurf, Cline, Continue, Zed, Goose). The assistant picks the right tool, calls the API, and answers with real data.

The server exposes 22 tools across eight categories: stock and ETF screening across 5 methodologies (AAOIFI, DJIM, FTSE, MSCI, S&P), bulk index screens, live quotes and price history, ETF holdings analysis, portfolio and watchlist scans, dividend and zakat calculators, news and SEC filings, plus report and education helpers. Every verdict is a methodology-based screen, not a fatwa.

Step 1: Get a free API key

Sign up at api.halalterminal.com. It is email-only, no credit card, and the key lands in your inbox in seconds. The free tier includes 500 tokens per month , which is plenty to evaluate the server before upgrading. Your key looks like ht_yourkey. Keep it handy for the next step.

Step 2: Connect your client

The fastest transport is the hosted SSE endpoint. For clients that need a local bridge, the @halalterminal/mcp package wraps it as stdio, and needs no install thanks to npx:

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

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

Claude Desktop

Open Settings, go to Developer, edit the config file, and add the server. Swap in your own key, then restart Claude Desktop:

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

Claude Code

One command from your terminal registers the hosted server over SSE:

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

Cursor, Windsurf, or any direct SSE client

Point the client at the SSE URL with your key as a query parameter:

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

That is it. The client discovers all 22 tools automatically. Auth is either the X-API-Key header or the ?api_key= query parameter, whichever your client supports.

Step 3: Ask your first questions

Type these as normal chat messages. The assistant maps each one to a tool and returns live results.

"Is AAPL halal?" calls screen_stock and returns a verdict under each of the 5 methodologies side by side. On our live screen at publication, Apple came back compliant across all five (AAOIFI, DJIM, FTSE, MSCI, and S&P). Verdicts move with the financials, so always trust the fresh result over any snapshot.
"Scan this portfolio: AAPL, MSFT, GOOGL" calls scan_portfolio and returns a per-holding verdict plus an overall compliant percentage for the basket.
"Calculate zakat on my holdings" calls calculate_zakat, applying 2.5% against a live nisab threshold once you give it your positions.
"Compare SPUS vs HLAL" calls compare_etfs and lines up the two funds on compliant percentage, holdings, and aggregate purification rate so you can judge which fits your standard.
"What is dividend purification for this stock?" calls get_dividends with purification enabled, computing the non-compliant fraction to donate.

Because the assistant reads the structured response, it can chain calls too: screen a stock, then pull its recent news and SEC filings in the same conversation.

Token costs

The API is token-metered, not request-metered. Typical calls cost roughly 1 to 5 tokens : a full stock screen is 5 tokens, so the free plan's 500 tokens covers about 100 screenings per month. Lighter reads like a quote or a search cost less. You can see the full per-endpoint table at /api/keys/token-costs, and check your remaining balance any time from the dashboard.

Build with Halal Terminal

Halal Terminal API

22 MCP tools, 5 screening methodologies, ETF holdings analysis, and zakat calculators. Free tier, no credit card.

Get your free API key -> Explore the API

Where to go next

Official MCP registry: find the server listed at registry.modelcontextprotocol.io.
GitHub repo: setup guides for every client, the full tool reference, and issue tracker at github.com/goww7/halalterminal-mcp.
API docs: the interactive reference lives at api.halalterminal.com/api-reference.

Five minutes in, your AI client speaks Shariah screening. Get your key at api.halalterminal.com and ask it something.

Important Disclaimer

Not financial advice. The information provided on this page is for educational and informational purposes only and should not be construed as financial advice, investment advice, trading advice, or any other type of advice. You should not make any financial decisions based solely on the information presented here.

Not a fatwa. Shariah compliance screening results are generated using automated data analysis based on publicly available financial data. These results do not constitute a religious ruling (fatwa) and should not be treated as one. Always consult a qualified Islamic scholar or Shariah advisor for guidance specific to your situation.

Do your own research. Past performance and current compliance status do not guarantee future results or continued compliance. Screening data may contain errors or become outdated. Always verify information independently and consult with a qualified financial advisor before making any investment decisions.

Originally published on the Halal Terminal blog.

DEV Community