Madeenan MCP server

Read-only MCP server for the Madeenan Quran and Hadith API. It gives Claude Desktop, Cursor, and other MCP hosts tools to search Quran, Hadith, Tafsir, and dua sources, read exact references, and collect evidence with citations. Docs: madeenan.com/docs/mcp.

• Quran MCP server overview
• Quran API and Hadith API
• Pricing

The server retrieves source records and prepares evidence bundles. It does not issue religious rulings or verify the meaning of a claim.

Install

The server needs Python 3.11 or later. With uv, run the published package without a separate install step:

uvx madeenan-mcp --check-config

Or install it into a virtual environment:

python3 -m venv .venv
. .venv/bin/activate
python -m pip install madeenan-mcp

The official packages are madeenan-mcp and madeenan-sdk. Their PyPI project links point to madeenan.com.

Install from a checkout

To work on the server, install both local packages from the repository:

cd /path/to/madeenan/apps/mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ../../packages/python
python -m pip install -e '.[dev]'

Keep the virtual environment active when you run madeenan-mcp from a terminal.

Check settings and configure a host

Run the local check before you add the server to a host:

madeenan-mcp --check-config

This command checks the API URL, timeout, HTTP bind port, and transport host and origin lists. It prints safe JSON and exits. It does not start the MCP server or contact the Madeenan API. The output reports whether an API key is set. It never prints the key. An invalid setting returns an error object and exit code 2.

For a client that uses the Claude Desktop or Cursor mcpServers JSON format, print a ready-to-copy stdio entry:

madeenan-mcp --print-config

With uvx, the stdio entry is:

{
  "mcpServers": {
    "madeenan": {
      "command": "uvx",
      "args": ["madeenan-mcp", "--transport", "stdio"]
    }
  }
}

For an installed package, --print-config uses the absolute path of the installed madeenan-mcp command. Neither form contains environment values or secrets. Add its mcpServers.madeenan entry to the host's existing config. Keep any other server entries in that file. This output is not a universal host format. For example, VS Code uses servers and sets type to stdio; Claude Code uses its claude mcp add command. See the MCP Python SDK host guide for current examples for each client.

The generated entry does not set MADEENAN_API_KEY. The server reads the key from its process environment. A shell variable reaches a host only when that host inherits the shell environment. A desktop app started from the Dock or Start menu may not inherit it. Set the key in the host's server environment settings or secret store. Some hosts save env values as plain text in a local config file. Protect that file and do not commit it. Never pass the key as an MCP tool argument.

Settings

The server reads these environment variables:

Variable	Default	Use
MADEENAN_API_KEY	Not set	Optional for current public source tools. Search access can have service limits.
MADEENAN_API_BASE_URL	https://api.madeenan.com	Madeenan API URL. It must use HTTP or HTTPS and must not include credentials, query values, or a fragment.
MADEENAN_TIMEOUT	30	API timeout in seconds. It must be greater than 0 and no more than 300.
MADEENAN_MCP_HOST	127.0.0.1	HTTP bind address.
MADEENAN_MCP_PORT	8000	HTTP bind port from 1 to 65535.
MADEENAN_MCP_ALLOWED_HOSTS	Derived for local use	JSON list of allowed HTTP Host values.
MADEENAN_MCP_ALLOWED_ORIGINS	None	JSON list of allowed browser origins.

The FASTMCP_TRANSPORT_SECURITY__ALLOWED_HOSTS and FASTMCP_TRANSPORT_SECURITY__ALLOWED_ORIGINS variables also set the host and origin lists. Each list must be JSON. For example:

export FASTMCP_TRANSPORT_SECURITY__ALLOWED_HOSTS='["mcp.example.com:*"]'
export FASTMCP_TRANSPORT_SECURITY__ALLOWED_ORIGINS='["https://mcp.example.com"]'

The Madeenan API key is optional for source lookups and search. The server does not expose the SDK's chat operation. The service can still limit public requests.

Run the server

For a local host, select stdio:

madeenan-mcp --transport stdio

The command waits for the MCP host. It can remain silent while it waits. MCP messages use stdout, so do not add print calls to server startup code. Use stderr for logs.

For a local HTTP process, use Streamable HTTP:

madeenan-mcp --transport streamable-http

The default MCP endpoint is /mcp. GET /health returns liveness and safe configuration status. An ASGI server can use madeenan_mcp.server:app:

uvicorn madeenan_mcp.server:app --host 127.0.0.1 --port 8000

The server has no built-in client authentication for HTTP. DNS rebinding host and origin allowlists do not authenticate users. Do not expose the endpoint to a public network by itself. Put it behind a gateway that enforces client authentication and TLS, or keep it on a trusted local network.

For a container, build from the repository root:

docker build -f apps/mcp/Dockerfile -t madeenan-mcp .
docker run --rm -p 8000:8000 madeenan-mcp

The container listens on 0.0.0.0:8000. Protect the endpoint with an authenticated gateway before you expose it outside a trusted network. Pass secrets through your deployment's secret settings. Do not add them to the image or commit them.

Tools

• search_islamic_sources: search source records.
• lookup_quran_reference: read a verse, chapter, or bounded passage.
• lookup_hadith_reference: read a Hadith and its grade metadata.
• lookup_dua: read a dua or adhkar item.
• find_quote_source: find wording matches. A match does not prove authorship.
• create_evidence_bundle: collect search results and requested source lookups.
• review_evidence_claim: prepare an evidence checklist. It does not verify a claim or its meaning.

The server also provides config://status and source_review_prompt.

Troubleshoot

• If --check-config returns ok: false, fix the setting named in its message, then run the check again.
• If a host cannot find the command, activate the venv before opening the host, or use the absolute command path from --print-config.
• If the host shows no tools, restart it after you change its config. Check the host's server log for startup errors.
• If a tool call fails, check the API URL and network access. Public search can also reach service limits. The API key is not a tool argument.
• If a remote HTTP host cannot connect, check the bind address, port, host list, origin list, and gateway. Allowlist entries do not provide client authentication.
• If you run stdio by itself, it waits for an MCP host. Silence is expected. Press Ctrl+C to stop the process.

License

MIT.