Skip to main content
Glama
MCP for IIIF Images
by mikeapp

MCP for IIIF Images

A Model Context Protocol (MCP) server for working with IIIF (International Image Interoperability Framework) manifests and images. See this video for a demonstration.

Features

This MCP server contains the following tools:

  • fetch_iiif_manifest: Fetch a IIIF manifest from a URL. (Note that clients may have difficulty processing large amounts of JSON.)

  • fetch_iiif_image: Retrieve a IIIF image from a base URI, fetching info.json and returning the image data (default: max 1500px dimension, max 800,000 pixels total)

  • fetch_iiif_image_region: Retrieve a specific region of a IIIF image using percentage coordinates, with the region scaled to fit within the same constraints

Caveats

  • The code scales the images to dimensions acceptable to Claude. It will not work with a Level 0 Image API implementation.

  • Claude may not process some IIIF Manifests due to the size of the file.

Related MCP server: IIIF MCP Server

Claude Desktop Configuration

Install from Claude Desktop Extension (DXT) file

  1. Install and log in to Claude Desktop

  2. Download the .dxt file from the latest release

  3. Double-click the .dxt file

  4. Install the extension when prompted by Claude

Install from Source Code

  1. Clone this repository

  2. Install dependencies: npm install

  3. Make the server executable: chmod +x server/server.js

To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file. Adjust the file path as necessary. You may also need to provide the full path to your node command.

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-iiif-images": {
      "command": "node",
      "args": ["/PATH/TO/mcp-iiif-images/server/server.js"]
    }
  }
}

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-iiif-images": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp-iiif-images\\server\\server.js"]
    }
  }
}

Linux

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-iiif-images": {
      "command": "node",
      "args": ["/path/to/mcp-iiif-images/server/server.js"]
    }
  }
}

General MCP Usage

The server supports two transport modes:

Standard Mode (stdio)

Run the server using stdio transport (default):

npm start
# or
node server/server.js

HTTP Streaming Mode

Run the server using HTTP streaming transport:

node server/server.js --http
# or with custom port
node server/server.js --http --port 8080

Command-line Options

  • --http: Use HTTP streaming transport instead of stdio

  • --port PORT: Port number for HTTP server (default: 3000)

  • --help: Show help message

When using HTTP mode, the server will start an HTTP server with the following endpoints:

  • GET /sse: Establish Server-Sent Events connection

  • POST /messages?sessionId=<id>: Send MCP messages

HTTP Streaming Mode

For HTTP streaming mode, you'll need to start the server manually with the --http flag and then configure Claude Desktop to connect via HTTP:

node server/server.js --http --port 3000

Then configure Claude Desktop to use the HTTP transport (refer to Claude Desktop documentation for HTTP transport configuration).

Note: Update the path in the args array to match the actual location where you've installed this server.

After updating the configuration, restart Claude Desktop for the changes to take effect.

Testing

To run the tests:

# Run tests once
npm test

# Run tests in watch mode (automatically re-runs on file changes)
npm run test:watch

# Run tests with coverage
npm test -- --coverage

The project uses Vitest as the testing framework, which provides:

  • Fast execution with ES modules support

  • Jest-compatible API with better error messages

  • Built-in coverage reporting

  • Watch mode for development

Available Tools

fetch_iiif_manifest

Fetches and validates a IIIF manifest from a URL.

Parameters:

  • url (required): The URL of the IIIF manifest to fetch

Example usage:

Please fetch the IIIF manifest from https://example.com/manifest.json

fetch_iiif_image

Retrieve a IIIF image from a base URI, fetching info.json and returning the image data.

Parameters:

  • baseUri (required): Base URI of the IIIF Image API resource (without /info.json)

Example usage:

Fetch the IIIF image at https://example.com/iiif/image123

fetch_iiif_image_region

Retrieve a specific region of a IIIF image using percentage coordinates, with the region scaled to fit within the same constraints. Use this to fetch regions of interest at higher detail for more accurate image description and analysis.

Parameters:

  • baseUri (required): Base URI of the IIIF Image API resource (without /info.json)

  • region (required): Region in pct: format (e.g., 'pct:20,20,50,50' for x,y,width,height as percentages)

Example usage:

Fetch a region from the IIIF image at https://example.com/iiif/image123 with region pct:10,10,50,50

Note that you can use these tools together in the course of a conversation, for example:

Fetch the IIIF image at https://example.com/iiif/image123 and describe it.
...
Zoom in on the text at the bottom of the page and transcribe it.

Available Tools

3 tools
fetch_iiif_imageA

Retrieve a IIIF image from a base URI, fetching info.json and returning the image data scaled to roughly 1M pixels total area.

Inputs: baseUri (required).

fetch_iiif_image_regionA

Retrieve a specific region of a IIIF image using percentage coordinates, with the region scaled to roughly 1M pixels total area. Use this to fetch regions of interest at higher detail for more accurate image description and analysis.

Inputs: baseUri (required), region (required).

fetch_iiif_manifestC

Fetch and validate a IIIF manifest from a URL

Inputs: url (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 3 tools

    Disambiguation4/5

    The tools are mostly distinct: fetch_iiif_image retrieves full images, fetch_iiif_image_region handles specific regions, and fetch_iiif_manifest deals with manifests. However, the first two tools could be confused as both fetch images, though the region variant is clearly specialized for partial extraction.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with 'fetch_iiif_' prefix, using snake_case uniformly. This predictability makes it easy for agents to understand and select the right tool.

    Tool Count3/5

    With only 3 tools, the set feels thin for a full IIIF image server, lacking operations like listing resources, updating metadata, or handling annotations. While it covers basic fetching, the scope is limited and may require workarounds for common workflows.

    Completeness2/5

    The tool surface is severely incomplete for IIIF image handling. It only supports fetching images, regions, and manifests, missing essential CRUD operations such as creating, updating, or deleting resources, and lacks tools for searching or managing collections, which are core to the IIIF domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers