Iconclass语义搜索MCP服务

rijksmuseum-iconclass-mcp

rijksmuseum-iconclass-mcp is an MCP server for searching and exploring Iconclass notations in natural language with an AI assistant. It was designed as a companion service for rijksmuseum-mcp+, an analogous resource for the Rijksmuseum's art collections.

The server provides access to over 1.3 million open-access Iconclass notations — all of the c. 39,000 base concepts and c. 1.3 million key-expanded variants that add modifiers like posture, context, or symbolism. Beside simple keyword matching, rijksmuseum-iconclass-mcp supports semantic search in natural language, so that you can discover iconclass notations related to concepts like "homesickness and exile" -> 94I2111 — "Ulysses longs for home" even when your exact search term doesn't appear in the notation text. You can also, for example, use the AI assistant to explore the Iconclass hierarchy, visualise its structure, or to request cataloguing advice. A separate CLI tool allows you to perform the same queries from the command-line.

It includes data from the Rijksmuseum showing how many artworks are tagged with a particular notation and is able (if rijksmuseum-mcp+ has also been installed) to seamlessly pass you back to that service to e.g. view an artwork with that notation. In addition, it returns a ready-made link to ArtResearch to let you view more artworks sharing this notation from the twelve member institutions in the PHAROS consortium.

This tool was developed as a technology demo by the Research and Infrastructure Support (RISE) group at the University of Basel. We are particularly interested in exploring the research opportunities, methodological risks, and technical challenges posed by retrieving and analysing data with LLMs. If you are interested in collaborating with us in this area, please get in touch.

Sample Queries

The system is designed to let you can search, explore and ask questions about the Iconclass in natural language. For examples of the kinds of queries it can answer, please see these example prompts. The links following each prompt demonstrate you that query was previously answered in Claude Desktop. For more examples, see the related discussion in the IconClass Forum.

Quick start

For the best results, add rijksmuseum-iconclass-mcp as a custom, remotely hosted connector in Claude Desktop or claude.ai using the URL below. This currently free for one custom connector – additional connectors requires a paid ('Pro') or higher subscription from Anthropic.

https://rijksmuseum-iconclass-mcp-production.up.railway.app/mcp

Go to Settings → Connectors → Add custom connector → name it as you like and paste the URL into the Remote MCP Server URL field. You can ignore the Authentication section. Once configured, optionally set the permissions for its tools (e.g. 'Always allow'). See Anthropic's instructions for details. Many other desktop and web-based clients such as OpenAI's ChatGPT or Mistral's LeChat and open-source applications support custom MCP servers. Please consult their documentation for more information.

Alternatively, you can install the Iconclass MCP server locally on your own computer; please consult the technical guide. A local install also gives you icmcp, a command-line interface that runs the same tools from the terminal, with JSONL output for piping into tools such as jq.

Recommended: Next, follow the same procedure to install its sibling resource, rijksmuseum-mcp+. This allows you to explore over 830,000 artworks and metadata records from the Rijksmuseum with semantic search, provenance analysis, similarity comparisons, and spatial reasoning.

Research skill

The rijksmuseum-iconclass-mcp.skill.zip file (.zip archive) is a research skill that gives the AI assistant detailed guidance on how best to use this resource effectively: which tool (see How it works) to choose for a given question type, how to combine searches, important metadata distinctions (e.g. subject terms vs iconclass notations), and known limitations. Installing the skill is optional but will significantly improve the quality and efficiency of your AI assistant's responses. Skill files were originally developed by Anthropic for their Claude products but have since become an open standard. The skill can be installed in Claude by following these instructions.

How it works

When you ask a question, your AI assistant sends it to the rijksmuseum-iconclass-mcp server using the Model Context Protocol (MCP) standard. The server holds a SQLite database of c. 1.3M Iconclass notations. Depending on the query, the server can search this database in two complementary ways: a fast full-text search that matches keywords, or a semantic search that uses vector embeddings (numerical representations of meaning) to find notations by concept rather than exact wording. A separate, small database records how many artworks in the Rijksmuseum collection are tagged with each notation, letting the server report back to a user not just what a code means but how many artworks exist for it. The server exposes six tools — search, browse, resolve, expand_keys, search_prefix, and find_artworks – which are described in more details below.

search — keyword or semantic search

Find notations by text or concept.

query: "crucifixion"          → 844 FTS matches across labels and keywords
semanticQuery: "domestic animals" → top matches by embedding similarity

Provide exactly one of query or semanticQuery.

browse — navigate the hierarchy

Explore a notation's place in the tree: path, children (expandable to depth 1–3), cross-references, key variants.

notation: "73D", depth: 2  → Passion of Christ, children + grandchildren
notation: "25F23", includeKeys: true  → 204 key-expanded variants

resolve — batch notation lookup

Look up one or more notations by code. Accepts a single string or an array of up to 25.

notation: ["73D6", "31A33", "25F23"]  → full metadata for each

expand_keys — key variant exploration

Given a base notation, return all its key-expanded variants with texts and collection data.

notation: "25F23"  → 204 variants (swimming, sleeping, fighting, etc.)

search_prefix — hierarchical subtree search

Find all notations under a hierarchy prefix. Leverages Iconclass's left-to-right encoding.

notation: "73D8"  → 8 notations under "instruments of the Passion"
notation: "25F"   → all animal notations

find_artworks — how many artworks use this subject?

Given one or more notations, check which collections have artworks tagged with those notations. Returns per-collection artwork counts and link-out URLs where available. An empty collections array means no loaded collection has artworks for that notation — try a parent or sibling notation instead.

notation: "73B57"  → Rijksmuseum: 24 artworks
notation: ["73D6", "92D192134"]  → batch lookup with counts

This currently only provides data from the Rijksmuseum in Amsterdam.

Technical Notes

For local setup (stdio or HTTP), deployment, architecture, data sources, and configuration, please see the technical guide.

graph TB
    Client["LLM Client<br/>(Claude, Mistral, etc.)"] --> HTTP["HTTP Server<br/>POST /mcp | GET /health"]

    HTTP --> MCP["MCP Server<br/>rijksmuseum-iconclass-mcp"]

    MCP --> T1["search"]
    MCP --> T2["browse"]
    MCP --> T3["resolve"]
    MCP --> T4["expand_keys"]
    MCP --> T5["search_prefix"]
    MCP --> T6["find_artworks"]

    T1 -->|"FTS keyword search"| DB["Iconclass DB"]
    T1 -->|"semantic query"| EMB["EmbeddingModel<br/>(EmbeddingGemma 2, 768d)"]
    EMB -->|"query vector"| DB

    T2 & T3 & T4 & T5 & T6 --> DB

    DB -->|"SQL queries"| MAIN["iconclass.db<br/>(1.3M notations, 13 languages,<br/>FTS5, KNN embeddings)"]
    DB -->|"ATTACH + JOIN"| COUNTS["iconclass-counts.db<br/>(artwork counts:<br/>Rijksmuseum)"]

    style Client fill:#e8f4f8,stroke:#2196F3
    style HTTP fill:#fff3e0,stroke:#FF9800
    style MCP fill:#f3e5f5,stroke:#9C27B0
    style T1 fill:#e8f5e9,stroke:#4CAF50
    style T2 fill:#e8f5e9,stroke:#4CAF50
    style T3 fill:#e8f5e9,stroke:#4CAF50
    style T4 fill:#e8f5e9,stroke:#4CAF50
    style T5 fill:#e8f5e9,stroke:#4CAF50
    style T6 fill:#e8f5e9,stroke:#4CAF50
    style DB fill:#fce4ec,stroke:#E91E63
    style EMB fill:#fce4ec,stroke:#E91E63
    style MAIN fill:#fff9c4,stroke:#FFC107
    style COUNTS fill:#fff9c4,stroke:#FFC107

Authors

Arno Bosse — RISE, University of Basel with Claude Code, Anthropic.

Citation

If you use rijksmuseum-iconclass-mcp in your research, please cite it as follows:

APA (7th ed.)

Bosse, A. (2026). rijksmuseum-iconclass-mcp (Version 0.7.0) [Software]. Research and Infrastructure Support (RISE), University of Basel. https://github.com/kintopp/rijksmuseum-iconclass-mcp

BibTeX

@software{bosse_2026_rijksmuseum_iconclass_mcp,
  author    = {Bosse, Arno},
  title     = {{rijksmuseum-iconclass-mcp}},
  year      = {2026},
  version   = {0.7.0},
  publisher = {Research and Infrastructure Support (RISE), University of Basel},
  url       = {https://github.com/kintopp/rijksmuseum-iconclass-mcp},
  orcid     = {0000-0003-3681-1289},
  note      = {Developed with Claude Code (Anthropic, \url{https://www.anthropic.com})}
}

License

MIT

Acknowledgements

The Iconclass classification system was created by Henri van de Waal and is maintained by the Iconclass Foundation. The data used in this server is published under a Creative Commons CC0 license.