Metadata-Version: 2.5
Name: madeenan-mcp
Version: 0.1.0
Summary: Read-only MCP server for the Madeenan Quran and Hadith API: search and read Quran, Hadith, Tafsir, and dua sources with citations
Project-URL: Homepage, https://madeenan.com
Project-URL: Documentation, https://madeenan.com/docs/mcp
Project-URL: Repository, https://github.com/itsmunzir/madeenan
Project-URL: Pricing, https://madeenan.com/pricing
Author: Madeenan
License-Expression: MIT
License-File: LICENSE
Keywords: citations,claude,cursor,dua,hadith,islamic,mcp,mcp-server,model-context-protocol,quran,rag,tafsir
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Religion
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: madeenan-sdk>=0.1.0
Requires-Dist: mcp<2,>=1.28
Requires-Dist: pydantic<3,>=2.8
Requires-Dist: uvicorn<1,>=0.30
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# Madeenan MCP server

<!-- mcp-name: com.madeenan/mcp -->

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](https://madeenan.com/docs/mcp).

- [Quran MCP server overview](https://madeenan.com/quran-mcp-server)
- [Quran API](https://madeenan.com/quran-api) and [Hadith API](https://madeenan.com/hadith-api)
- [Pricing](https://madeenan.com/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](https://docs.astral.sh/uv/),
run the published package without a separate install step:

```shell
uvx madeenan-mcp --check-config
```

Or install it into a virtual environment:

```shell
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:

```shell
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:

```shell
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:

```shell
madeenan-mcp --print-config
```

With uvx, the stdio entry is:

```json
{
  "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](https://py.sdk.modelcontextprotocol.io/get-started/real-host/)
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:

```shell
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:

```shell
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:

```shell
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`:

```shell
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:

```shell
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.
