Quran

What Quran MCP server does

The Quran MCP server gives MCP-compatible AI clients access to Quran content through four focused tools. It can enumerate all 114 surahs, retrieve a complete surah, retrieve one ayah, and search verses for a keyword. Results include identifying information such as surah and ayah numbers where relevant, making the server suitable for verse lookup and basic text exploration.

list_surahs returns each chapter's Arabic name, English name, English translation, verse count, and revelation type. get_surah retrieves every ayah in a selected chapter. get_ayah accepts either a chapter-and-verse reference such as 2:255 or a global ayah number from 1 through 6236. search_quran returns up to 30 matching verses and defaults to the en.asad English translation.

How it works

The hosted MCP connection is available at https://gateway.pipeworx.io/quran/mcp. It exposes the Quran pack's tools along with shared Pipeworx gateway tools. The gateway can also route broader questions through ask_pipeworx, which is useful when a request extends beyond the Quran pack. A full gateway connection is available at https://gateway.pipeworx.io/mcp if an agent needs all catalog sources listed directly.

The same functionality can run locally through the @pipeworx/mcp-quran npm package. The local process communicates over standard input and output and serves only the four Quran-specific tools. HTTP access is also available through the gateway's tool endpoint, such as a POST request to /v1/tools/list_surahs.

Setup and configuration

For a hosted connection, add the gateway URL to the MCP client's server configuration:

{
  "mcpServers": {
    "quran": {
      "url": "https://gateway.pipeworx.io/quran/mcp"
    }
  }
}

For a local stdio connection, configure the client to run npx -y @pipeworx/mcp-quran.

Tools and capabilities

• List all 114 surahs with names, verse counts, and Meccan or Medinan classification.
• Retrieve a full surah in a selected edition.
• Retrieve one ayah by surah:ayah reference or global number.
• Search up to 30 matching ayahs by keyword.
• Use en.asad or en.sahih for supported English translation examples, or quran-uthmani for Arabic text.

The edition is selected when calling the retrieval and search tools. Search defaults to en.asad, but another translation or the Arabic edition can be supplied.

Limitations and notes

The server exposes Quran retrieval and search functions rather than general religious research or interpretation tools. Search results are capped at 30 matching verses. Surah numbers must be between 1 and 114, while global ayah references must be between 1 and 6236.

A hosted pack endpoint includes shared Pipeworx meta-tools in addition to the four Quran tools, so its tool list is larger than the local package's list. The gateway's initialization response is the authoritative source for the exact tools exposed at connection time. The project is licensed under MIT.