Skip to main content
Glama
art-institute-chicago-mcp-server

art-institute-chicago-mcp-server

by cyanheads
README.md
<div align="center">
  <h1>@cyanheads/art-institute-chicago-mcp-server</h1>
  <p><b>Search the Art Institute of Chicago collection: artworks, artists, exhibitions, and audio guides via MCP. STDIO or Streamable HTTP.</b>
  <div>6 Tools • 1 Resource</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.3.1-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/art-institute-chicago-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/art-institute-chicago-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/art-institute-chicago-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/art-institute-chicago-mcp-server/releases/latest/download/art-institute-chicago-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=art-institute-chicago-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvYXJ0LWluc3RpdHV0ZS1jaGljYWdvLW1jcC1zZXJ2ZXIiXX0=) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22art-institute-chicago-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fart-institute-chicago-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://art-institute-chicago.caseyjhand.com/mcp](https://art-institute-chicago.caseyjhand.com/mcp)

</div>

---

## Overview

The Art Institute of Chicago's collection: about 133,000 artworks, plus artists, exhibitions, and audio-guide stops. Search with filters and facet counts, read full records with provenance and IIIF image URLs, and search audio-guide transcripts. No API key required.

### Tools

| Tool | Description |
|:---|:---|
| `artic_search_artworks` | Search artworks by text and filters, with facet counts and date or acquisition-year sorting |
| `artic_get_artworks` | Fetch full records for up to 100 artworks: description, provenance, histories, image URLs with rights status, related media |
| `artic_search_artists` | Find artists, cultures, and organizations by name or id, with available Getty ULAN identifiers, life dates, artwork counts, and sample works |
| `artic_search_exhibitions` | Search past, current, and upcoming exhibitions by text, date, artwork id, or artist id |
| `artic_search_audio_guide` | Search audio-guide stops by text: title, MP3 URL, and transcript |
| `artic_lookup_vocabulary` | List the values a search filter accepts, with artwork counts |

### Resources

| Resource | Description |
|:---|:---|
| `artic://artworks/{id}` | One artwork record as JSON, with the API license text and description attribution |

`artic_get_artworks` returns the same record for clients that don't surface resources.

### Skills

| Skill | Description |
|:---|:---|
| `art-institute-chicago-guide` | Gates and workflows the tool descriptions don't carry: finding works by an artist or culture, a work's exhibition history, counts past the 1,000-match window, provenance research and acquisition years, audio-guide stops versus linked media, accent-exact filter values, and reuse terms per output |

The server serves it over MCP as `skill://art-institute-chicago-guide/SKILL.md`; it also ships in `skills/` in the npm package and Docker image.

## Capability reference

Searches and vocabulary lookup accept limits up to 1,000, and the response states the cap actually applied: 100 rows for artworks, artists, exhibitions, and the audio guide, and 1,000 values for vocabulary. Defaults are 10 rows (audio guide 2, vocabulary 25). Keep the same requested limit when following `next_page`; page times applied size must stay within 1,000. At the vocabulary cap, narrow with `contains`.

### `artic_search_artworks` <sub>tool</sub>

- `query` (every word must match, except common English words such as the and of, which are ignored; `"exact phrase"`, `-exclude`, and `a | b` work) plus filters `artist`, `artist_id`, `department`, `artwork_type`, `style`, `subject`, `classification`, `material`, `technique`, `theme`, `place_of_origin`, `gallery`, `year_from` / `year_to` (date-span overlap, negative for BCE), `acquired_from` / `acquired_to` (fiscal year of acquisition, inclusive; works with no recorded year never match), `public_domain_only`, `on_view_only`, and `has_image`, combined with AND
- Up to 100 rows per page (default 10), within the first 1,000 matches; rows carry `main_reference_number` and, when recorded, `acquisition_fiscal_year`. `sort` is `relevance`, `date_asc`, `date_desc`, `acquired_desc` (recent acquisitions first), or `acquired_asc`; works missing the sorted field come last, and `sort_applied` reports `popularity` when relevance had no query text
- `facets` adds the top 15 values for any of 11 fields (the ten vocabularies and `artist`; `artist` counts every credited artist and rows carry `artist_id`); `limit: 0` returns counts only

---

### `artic_get_artworks` <sub>tool</sub>

- `ids` takes up to 1,000 entries (comma strings up to 100,000 characters); blanks and duplicates are dropped and artwork page URLs are read as ids. The first 100 are fetched; `sections` chooses from description and provenance (default), exhibition_history, publication_history, and catalogue, and is the size lever: every section on 100 well-documented works comes to about 1.4 MB
- Records return whole, in request order. `missing_ids` lists ids the museum doesn't have; `deferred_ids` lists ids past the first 100, to pass to the same tool again
- `include_related_media` (default on) loads up to 100 linked lectures and audio stops; `description_attribution` appears whenever CC BY description text is returned

---

### `artic_search_artists` <sub>tool</sub>

- `query` (all name words must match) or `ids`, not both; ids takes up to 1,000 entries (comma strings up to 100,000 characters) and the first 100 are fetched. Query mode adds `artists_only` (default `true`), `born_from` / `born_to`, and up to 100 agents per page
- Each agent carries `artwork_count`, up to three `sample_works` (the museum's highlights first), life years, and `alt_names`; ids mode reports `missing_ids` and `deferred_ids` to pass as ids in the next call
- `ulan_id` is the Getty ULAN identifier when the museum records one; coverage is sparse, and it is distinct from the museum `id` used by other tools

---

### `artic_search_exhibitions` <sub>tool</sub>

- `query`, `when` (`current`, `upcoming`, `past`, or the default `any`), `date_from` / `date_to` (`YYYY-MM-DD`, matched by run overlap), and exact `artwork_id` / `artist_id` filters, combined with AND; up to 100 per page within the first 1,000 matches. `query` ignores common English words such as the and of
- Relationship filters cover recorded museum links; absent links do not prove an artwork or artist never appeared in a show
- `sort` is `relevance`, `start_desc`, or `start_asc`, defaulting to relevance with a query and `start_desc` without; `status` is the museum's label and doesn't say whether a show is open (`when` does)
- A missing date is unrecorded, not a run that did not happen: a show with no closing date is past when marked `Closed`, else current from its opening, and a date window reads it as running on its opening date alone (`Closed`) or on from it; a show with only a closing date ran on that date alone, and one with no dates matches no window
- Rows carry dates, gallery, summary, web page, image, `artist_ids`, and the `artworks` shown, when the museum lists them

---

### `artic_search_audio_guide` <sub>tool</sub>

- `query` is required and matches stop titles and transcripts (every word except common English words such as the and of, which are ignored); up to 100 whole stops per page (default 2)
- Each stop has `title`, `audio_url` (MP3), and `transcript` but no artwork id; every response carries `license_text` and `source_citation` (content is for noncommercial educational and personal use)

---

### `artic_lookup_vocabulary` <sub>tool</sub>

- `vocabulary` is one of `department`, `artwork_type`, `style`, `subject`, `classification`, `material`, `technique`, `theme`, `place_of_origin`, or `gallery`; optional `contains` substring (ignoring case and accents, so `applique` finds `appliqué (technique)`), `public_domain_only`, and up to 1,000 values (default 25)
- Values come back most common first with `artwork_count`, in the exact form the `artic_search_artworks` filter of the same name accepts; `filter_param` names that filter

---

### `artic://artworks/{id}` <sub>resource</sub>

- `{ artwork, license_text, description_attribution?, notice? }` as `application/json`, where `artwork` is the `artic_get_artworks` record with its default sections and related media
- An unknown id fails as `artwork_not_found`; ids come from `artic_search_artworks`

## Features

Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio and Streamable HTTP transports, pluggable auth (`none` / `jwt` / `oauth`), swappable storage (`in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`), structured logging with optional OpenTelemetry tracing.

Art Institute-specific:

- Keyless access to the Art Institute of Chicago public API (`api.artic.edu/api/v1`); IIIF image URLs are built from each record (843 px for every image, 1686 px and a IIIF manifest for public-domain works), never fetched
- One shared request pacer under the API's published limit of 60 requests a minute, retries for transient failures inside a 20-second deadline, and an in-process response cache (records 6 hours, searches 15 minutes, vocabularies 24 hours)
- Text search requires every word to match, except common English words such as the and of, which are ignored, so totals are real and a miss reads as zero hits; results keep the museum's relevance order
- Placeholder years in the museum's data (outside −8000 to 2100) are left out of output, year filters, and date sorts; `date_display` stays the authority. Date and acquisition sorts keep works with no value for the sorted field and list them last

Agent-friendly output:

- Rights travel with the data: `image.rights` (`public_domain` / `in_copyright`) on every image, with the 1686 px URL only where reuse is allowed; the API's `license_text` verbatim; `description_attribution` when CC BY text is returned; `source_citation` on audio-guide results
- Partial results instead of failures: `artic_get_artworks` reports `missing_ids` and `deferred_ids`, and when a secondary lookup (related media, artist counts) fails, the primary records still return with a `notice` naming what is missing
- Paging that names the next move: `totalCount`, `has_more`, `next_page`, and a `notice` for the next page, the 1,000-match ceiling, or the filter to loosen after zero hits

## Data and licensing

The Art Institute of Chicago licenses its API data by surface, and the server passes the API's own `license_text` through with every artwork, artist, exhibition, and audio-guide result:

| Content | Terms |
|:---|:---|
| Artwork metadata, artists, exhibitions, vocabulary terms, related media | CC0 |
| Artwork `description` text | CC BY 4.0: credit the Art Institute of Chicago and cite the record's `web_url` |
| Artwork images | Reusable only for public-domain works (`image.rights: "public_domain"`, CC0); other images need a rights check |
| Audio-guide content | Noncommercial educational and personal use, with copyright notices kept and the source cited |

This server is an independent project and is not affiliated with or endorsed by the Art Institute of Chicago.

## Known limitations

- Only the first 1,000 matches of any search are reachable without an authenticated key. Broad questions need filters or facets.
- The API's limit of 60 requests a minute is per egress IP, so every client behind one IP shares it. A call that cannot start within its 20-second budget fails as `rate_limited`.
- Curatorial text is sparse: about 10% of artworks have a `description`, and in a general sample 94% lack provenance. About 1% of artists have a biography, and there is no nationality field, only `artist_display` prose.
- About 15 artworks carry placeholder years and about 4,900 carry no dates; neither matches a year filter.
- About a third of artworks (47,677 of 133,165, 2026-11-03) have no recorded acquisition fiscal year; they never match `acquired_from` / `acquired_to` and sort last by acquisition year.
- Some vocabulary titles are stored cut at 40 characters in the museum's data (`gelatin silver (developing-out-paper) pr`). Pass values as `artic_lookup_vocabulary` lists them.
- The API's firewall refuses any request whose text contains markup such as `<script>`; the call fails as `request_blocked`.
- About 4% of exhibitions list their artworks. 650 of 6,262 have no recorded closing date (2026-11-03); the date filters read those as described above.
- Audio-guide stops have no artwork link. Some titles are file names, and some transcripts are in Spanish.
- Image URLs can stop resolving when the museum unpublishes or replaces an image, and relevance order follows the museum's ranking, which may shift.

## Getting started

Connect to the hosted instance, no install:

```sh
claude mcp add --transport http art-institute-chicago-mcp-server https://art-institute-chicago.caseyjhand.com/mcp
```

Every caller of the hosted instance shares one `api.artic.edu` request budget of 50 requests a minute. For sustained use, run your own instance.

Or run it locally:

```sh
claude mcp add art-institute-chicago-mcp-server -- npx -y @cyanheads/art-institute-chicago-mcp-server
```

For other clients, add this to the MCP config file:

```json
{
  "mcpServers": {
    "art-institute-chicago-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/art-institute-chicago-mcp-server"]
    }
  }
}
```

No API key or account is needed. The Art Institute API asks clients to identify themselves: set `AIC_CONTACT` to an email or URL the museum can reach (see [Configuration](#configuration)). For Docker or a source build, see [Running the server](#running-the-server).

## Configuration

| Variable | Description | Default |
|:---|:---|:---|
| `AIC_CONTACT` | Email or URL the museum can reach, sent in the `AIC-User-Agent` header. Printable ASCII only; the server refuses to start otherwise. Set your own for any deployment. | `https://github.com/cyanheads/art-institute-chicago-mcp-server` |
| `AIC_REQUESTS_PER_MINUTE` | Outbound requests per minute to `api.artic.edu`, 1–600. Stays under the API's published limit of 60; raise it only if the museum grants a higher one. | `50` |
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
| `MCP_HTTP_PORT` | HTTP server port. | `3010` |
| `MCP_SESSION_MODE` | HTTP session mode: `stateless`, `stateful`, or `auto`. Overrides the server's declared posture. | `stateless` |
| `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth`. | `none` |
| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.). | `info` |
| `LOGS_DIR` | Directory for log files (Node.js only). | `<app-root>/logs` |
| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`. | `in-memory` |
| `OTEL_ENABLED` | Enable [OpenTelemetry](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |

See [`.env.example`](./.env.example) for every server setting and the common framework overrides.

## Running the server

### Local development

Requires [Bun v1.4.0](https://bun.sh/) or higher (or Node.js v24+).

- **Clone and install:**

  ```sh
  git clone https://github.com/cyanheads/art-institute-chicago-mcp-server.git
  cd art-institute-chicago-mcp-server && bun install
  cp .env.example .env   # set AIC_CONTACT
  ```

- **Build and run:**

  ```sh
  # One-time build
  bun run rebuild

  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  ```

- **Run checks and tests:**

  ```sh
  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  ```

### Docker

```sh
docker run --rm -e AIC_CONTACT=you@example.com -p 3010:3010 ghcr.io/cyanheads/art-institute-chicago-mcp-server:latest
```

The image defaults to HTTP transport, stateless session mode, and logs to `/var/log/art-institute-chicago-mcp-server`. To run it over stdio from an MCP client, use `"command": "docker"` with `"args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "-e", "AIC_CONTACT=you@example.com", "ghcr.io/cyanheads/art-institute-chicago-mcp-server:latest"]`. To build locally, `docker build -t art-institute-chicago-mcp-server .`; OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.

## Project structure

| Directory | Purpose |
|:---|:---|
| `src/index.ts` | `createApp()` entry point: registers the tools and resource, sets the server instructions, and starts and stops the API service. |
| `src/config` | `AIC_CONTACT` and `AIC_REQUESTS_PER_MINUTE` parsing and validation with Zod. |
| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`) and the artwork output schema they share. |
| `src/mcp-server/resources` | The `artic://artworks/{id}` resource. |
| `src/services/aic` | Art Institute API client: pacing, retries, response cache, HTML-to-text, IIIF URL construction, and the artwork and artist record builders. |
| `skills/` | The published `art-institute-chicago-guide` Agent Skill, served over MCP. |
| `tests/` | Unit and integration tests, mirroring the `src/` structure. |

## Development guide

See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:

- Handlers throw, framework catches — no `try/catch` in tool logic
- Use `ctx.log` for logging, `ctx.enrich` for paging and notices
- Register new tools and resources in the barrels under `src/mcp-server/*/definitions/index.ts`
- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

## Contributing

Issues are welcome. Run checks and tests before submitting:

```sh
bun run devcheck
bun run test
```

## License

This project is licensed under the Apache 2.0 License. See the [LICENSE](./LICENSE) file for details.