IWAC MCP Server

A read-only Model Context Protocol server for the Islam West Africa Collection (IWAC). Ships as a one-click Desktop Extension (.mcpb) for Claude Desktop, backed by the IWAC Hugging Face dataset. Also available as a hosted endpoint at https://islam.zmo.de/mcp/ for ChatGPT and other MCP clients — see docs/connecting.md for the full connection walkthrough (Claude Desktop and ChatGPT).

Install

Each release ships a server bundle for your operating system plus a research-skill .zip. The .mcpb gives Claude the data and tools; the .zip adds a research skill that teaches Claude how to use them. Install the server first, then install the skill too — strongly recommended for getting the most out of the tools: it makes Claude search and synthesize far more efficiently, with fewer wasted queries.

1. The MCP server — pick the bundle for your OS

1. Download the latest bundle for your OS using the links above.
2. Double-click the file. Claude Desktop shows an install dialog — click Install.
3. On first use the server downloads ~250 MB of parquet data from Hugging Face into ~/.iwac-mcp/cache/ (override in the extension settings).

The bundle contains the server and DuckDB binaries for your OS (x64 and arm64). Claude Desktop supplies the Node.js runtime, so no separate Node.js or Python installation is needed. We publish desktop bundles for Windows and macOS.

Extension settings and updates

Open Settings → Extensions → Islam West Africa Collection (IWAC) in Claude Desktop to configure these options:

Semantic search and private access are independent options. Using both requires both credentials. The shared hosted endpoint serves public data.

Updating: download and open the latest bundle for your OS to update the extension. If the Hugging Face fields are missing, your installed extension may predate v3.6.0. After updating, review the settings, save any changes, and restart Claude Desktop.

Optional private full-text access

Public data remains the default and needs no token. In the desktop extension, enable Use private full dataset, enter the Hugging Face token (private dataset only), save the settings, and restart. Use a fine-grained token with read access to fmadore/islam-west-africa-collection-full. The token field is marked sensitive. Never paste your token into a chat or commit it.

Other local launchers can set IWAC_PRIVATE_DATASET=true and provide IWAC_HF_TOKEN (or HF_TOKEN). A token alone does not enable private mode; public downloads do not send it. No new dependency or account system is needed.

Private files use a separate private-full/ subdirectory of IWAC_CACHE_DIR (default: ~/.iwac-mcp/cache). Restart after changing modes. Missing tokens and private HTTP 401/403/404 errors fail without cache fallback. Network outages may use that mode's cache. Explicit IWAC_OFFLINE=true uses downloaded files without authentication; removing a token does not erase private files.

Keep the shared hosted endpoint public. This setting applies to the whole instance: everyone who can query a private instance can access its full text.

2. The research skill — iwac-mcp-skill.zip (strongly recommended)

The iwac-mcp skill wraps the raw tools in a structured research workflow: a five-phase methodology, francophone search strategy, source attribution with confidence grading, and bias/coverage caveats. It makes the server far more efficient to use — Claude picks the right tool and search terms on the first pass (fewer wasted queries), searches French sources properly, and returns a cited synthesis instead of a raw tool dump. You can run the tools without it, but you'll get more out of every query with it installed.

Download the latest iwac-mcp-skill.zip, then:

• Claude Desktop — open Customize → Skills → + → Create skill → Upload a skill and select the zip. (Or unzip it into ~/.claude/skills/ and restart Claude Desktop.)

• Claude Code — unzip it into your skills directory; Claude Code discovers it live, no restart needed:

  bash

  Copy

  # macOS / Linux
  unzip iwac-mcp-skill.zip -d ~/.claude/skills/
  

  powershell

  Copy

  # Windows (PowerShell)
  Expand-Archive iwac-mcp-skill.zip -DestinationPath $HOME\.claude\skills\
  

  Both land the skill at ~/.claude/skills/iwac-mcp/. The repository source of truth is .agents/skills/iwac-mcp/; keep project-local copies there rather than duplicating the same skill under .claude/.

  Installing it this way is still worth doing: an installed skill is matched against your question automatically, before any tool is called.

The server also serves the skill (skill://, prototype)

Prototype. This is an experiment tracking a draft spec, not a supported interface. The URIs and the catalogue shape may change or be withdrawn without a major version bump. Installing the skill from the .zip above is still the supported path on Claude Desktop and Claude Code. Do not rely on skill:// in anything you build.

Every build also embeds the skill and exposes it as MCP resources, so a client that has not installed it can still read it:

A host that implements the draft extension can instead discover the same catalogue through skills/list and skills/get, which the server declares via the io.modelcontextprotocol/skills capability. Both routes read one catalogue, so they cannot disagree.

This matters most for the remote HTTP endpoint, where there is no release artifact to download: add the connector and the manual comes with it. The server's handshake instructions point at skill://iwac-mcp/SKILL.md, and nothing is pushed into the context until something asks for it.

The shape follows SEP-2640 ("Skills over MCP"), an open draft PR against the MCP spec: not accepted, and subject to change. Two routes reach the same catalogue: the resources/* one above, which every current client already speaks, and the extension's own skills/list / skills/get, for hosts that implement the draft. The SEP's one optional method, resources/directory/read, is not served — the bare skill://iwac-mcp is this server's catalogue document and cannot also be a directory resource — so the capability is declared without directoryRead. If the SEP changes shape or is rejected, all of this moves with it.

What it gives Claude

37 possible read-only tools across seven IWAC subsets. 34 work out of the box; the 3 semantic_search_* tools are optional and require a free Google/Gemini API key (disabled by default). All keyword and filter matching is accent- and case-insensitive. The unified search/fetch pair, the stats tools, the aggregates, list_periodicals, and get_sentiment_distribution also return MCP structured content (outputSchema + structuredContent), which the ChatGPT connector contract requires.