Maktabah MCP Server

Model Context Protocol — AI Agent Integration

MCP (Model Context Protocol) is an open standard that lets AI agents like Claude Code, Cursor, VS Code, OpenCode, and Codex access tools and data directly. This server exposes the Maktabah Wiki collection as MCP tools — so your AI agent can search and read kitab content in real time.

Architecture

AI Agent (Claude Code / Cursor / Codex) │ JSON-RPC over stdin ▼ maktabah-mcp (local binary) │ HTTPS ▼ maktabah.underconst.com ├── /api/search/sections?full=true ├── /api/search/books └── /api/search/authors

Available Tools

search_kitab(q, limit?)

Semantic search across kitab sections. Returns full text chunks from Qdrant vector search with reranking.

search_books(q)

Search books by title using Meilisearch keyword search.

search_authors(q)

Search scholars and authors by name using Meilisearch keyword search.

Quick Install — AI Prompt

Copy the prompt below and paste it into your AI agent (Claude Code, Codex, OpenCode, etc.). The agent will handle installation automatically.

INSTALL MAKTABAH MCP SERVER

1. Detect the OS and architecture of this machine
2. Download the matching binary:
   - Linux amd64 → https://maktabah.underconst.com/mcp/maktabah-mcp-linux-amd64
   - macOS amd64 → https://maktabah.underconst.com/mcp/maktabah-mcp-darwin-amd64
   - macOS arm64 → https://maktabah.underconst.com/mcp/maktabah-mcp-darwin-arm64
   - Windows amd64 → https://maktabah.underconst.com/mcp/maktabah-mcp-windows-amd64.exe
3. Save to ~/.local/bin/maktabah-mcp (Linux/macOS) or %%USERPROFILE%%\.local\bin\maktabah-mcp.exe (Windows)
4. Make it executable (chmod +x on Linux/macOS)
5. Register the MCP server with this configuration:
   {
     "maktabah": {
       "type": "local",
       "command": [
         "~/.local/bin/maktabah-mcp",
         "--base-url",
         "https://maktabah.underconst.com"
       ]
     }
   }
   - Claude Code: ~/.claude/mcp-servers.json
   - Cursor: ~/.cursor/mcp.json
   - OpenCode: ~/.config/opencode/settings.json
   - VS Code: .vscode/mcp.json
6. Verify: ~/.local/bin/maktabah-mcp --help
7. Tools available:
   - search_kitab(q, limit) — semantic search kitab content (full text)
   - search_books(q) — search books by title
   - search_authors(q) — search authors by name

Manual Installation

# Download
curl -sfL https://maktabah.underconst.com/mcp/install.sh | sh

# Or manually:
mkdir -p ~/.local/bin
curl -fL https://maktabah.underconst.com/mcp/maktabah-mcp-linux-amd64 -o ~/.local/bin/maktabah-mcp
chmod +x ~/.local/bin/maktabah-mcp

# Add to PATH (if not already)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Download
curl -sfL https://maktabah.underconst.com/mcp/install.sh | sh

# Intel Mac:
curl -fL https://maktabah.underconst.com/mcp/maktabah-mcp-darwin-amd64 -o ~/.local/bin/maktabah-mcp

# Apple Silicon:
curl -fL https://maktabah.underconst.com/mcp/maktabah-mcp-darwin-arm64 -o ~/.local/bin/maktabah-mcp

chmod +x ~/.local/bin/maktabah-mcp

Configuration

Claude Code / Cursor

{
  "mcpServers": {
    "maktabah": {
      "command": "/home/user/.local/bin/maktabah-mcp",
      "args": ["--base-url", "https://maktabah.underconst.com"]
    }
  }
}

~/.claude/mcp-servers.json or ~/.cursor/mcp.json

OpenCode

{
  "mcpServers": {
    "maktabah": {
      "type": "local",
      "command": [
        "/Users/user/.local/bin/maktabah-mcp",
        "--base-url",
        "https://maktabah.underconst.com"
      ]
    }
  }
}

~/.config/opencode/settings.json

VS Code

{
  "mcpServers": {
    "maktabah": {
      "command": "/home/user/.local/bin/maktabah-mcp",
      "args": ["--base-url", "https://maktabah.underconst.com"]
    }
  }
}

.vscode/mcp.json (project-level)

Verify

Test the MCP server directly from your terminal:

# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ~/.local/bin/maktabah-mcp --base-url https://maktabah.underconst.com

# Search kitab content
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_kitab","arguments":{"q":"zakat","limit":2}}}' | ~/.local/bin/maktabah-mcp --base-url https://maktabah.underconst.com

API Reference

The MCP server is a wrapper around these REST endpoints:

GET /api/search/sections?q=&full=true

GET /api/search/books?q=

GET /api/search/authors?q=