Overview

The IIIF MCP Server implements the Model Context Protocol (MCP) for IIIF (International Image Interoperability Framework) resources, providing a focused server-side toolkit to search, navigate, and manipulate IIIF manifests, collections, canvases, images, annotations, and change streams. It is designed for museums, libraries, and archives that need an interoperable, programmable backend to power viewers, discovery interfaces, and integration with downstream tools.

Built to work with IIIF Presentation, Image, Search, Auth, and Change Discovery APIs (v2 and v3 where applicable), the server exposes higher-level operations — full-text search, metadata extraction, image URL generation and fetching, annotation aggregation, and access-control flows — so developers can add IIIF-aware features without reimplementing protocol details.

Features

Core
- Full-text search across IIIF resources (Search API v0/v1/v2 support)
- Metadata retrieval for manifests and collections (Presentation API v2 & v3)
- IIIF Image API support: build validated URLs and fetch image info
- Authentication flows compatible with IIIF Auth API (cookie & token flows)
Image & Canvas Operations
- Build IIIF Image API URLs with region/size/rotation/quality/format validation
- Fetch actual image content (Base64) with parameterized cropping and sizing
- Canvas listing and detailed canvas info extraction (multi-image canvases supported)
Collections, Annotations & Change Tracking
- List and traverse collections and manifests (hierarchical navigation)
- Search and extract annotations with multilingual support and motivation filters
- Monitor resource updates via IIIF Change Discovery API (activity streams)
Media & Access
- Audio/video item extraction, duration calculation, and technical metadata
- Access control probe and session management for protected IIIF resources
Distribution
- Standard npm build plus single-file bundle option (esbuild) for npm-free deployment

Installation / Configuration

Standard install (development / production with npm toolchain):

git clone https://github.com/code4history/IIIF_MCP.git
cd IIIF_MCP
npm install
npm run build

Create a single-file bundle (no npm on target host required):

npm run bundle
# Produces iiif-mcp-bundle.js for standalone deployment

Basic runtime configuration example (environment variables or JSON config):

{
  "maxImageDimension": 1500,
  "maxImagePixels": 1000000,
  "iiifTimeoutMs": 10000,
  "auth": {
    "enableProbe": true,
    "sessionTimeoutSec": 3600
  }
}

Notes:

Image fetch operations automatically enforce safe limits (default: max 1500px or 1M pixels) to avoid excessive resource use.
Supports Presentation API v2 and v3 formats; configure behavior if your installation is strictly one version.

Available Resources

Common server endpoints and their purpose:

Endpoint	Purpose
/search	Full-text search across indexed manifests and annotations
/manifest/:id	Fetch manifest metadata normalized for v2/v3
/collection/:id	List collections and contained manifests
/canvas/:id	Canvas metadata and available image services
/image/fetch	Fetch image content with IIIF parameters (returns Base64)
/auth/probe	Verify access and trigger IIIF auth flow
/changes	Change stream (Change Discovery) navigation

See the GitHub repository for API reference and examples: https://github.com/code4history/IIIF_MCP

Use Cases

Thumbnail & Cropping Service
- Generate on-demand thumbnails or cropped regions for a IIIF canvas, returning Base64-encoded image payloads for lightweight embedding in web apps.
Enhanced IIIF Viewer Backend
- Power IIIF viewers with a server that resolves manifests/collections, normalizes metadata, provides search results, and handles restricted-content authentication flows.
Cross-Collection Search & Discovery
- Index and search full text and annotation text across multiple IIIF collections to build discovery portals that combine OCR, transcriptions, and metadata search.
Collections Management & Reporting
- Traverse nested collections, list manifests and canvases, extract durations and technical metadata for A/V holdings, and produce inventory or exhibit-ready lists.
Change Monitoring & Sync
- Subscribe to IIIF Change Discovery streams to detect create/update/delete activities and trigger downstream indexing or archival workflows.

Quick Example

Fetch a cropped image region (client-side pseudocode):

const res = await fetch('/image/fetch', {
  method: 'POST',
  body: JSON.stringify({
    iiifUrl: 'https://example.org/iiif/2/abcd',
    region: 'pct:10,10,50,50',
    size: '!300,300',
    quality: 'default',
    format: 'jpg'
  })
});
const { base64Image } = await res.json();
// use "data:image/jpeg;base64," + base64Image in an <img> tag

Where to Start

Clone the repo and run the build to inspect example routes.
Try the single-file bundle for quick embedding into static servers.
Review the sample configuration and adjust image size/policy settings to match your deployment constraints.

For full API details, examples, and contribution guidelines, see the project on GitHub: https://github.com/code4history/IIIF_MCP

IIIF MCP Server for Museums, Libraries, Archives