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">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/art-institute-chicago-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/art-institute-chicago-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](https://github.com/cyanheads/art-institute-chicago-mcp-server/releases/latest/download/art-institute-chicago-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=art-institute-chicago-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvYXJ0LWluc3RpdHV0ZS1jaGljYWdvLW1jcC1zZXJ2ZXIiXX0=) [](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)
[](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 sorting |
| `artic_get_artworks` | Fetch full records for up to 10 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, 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: artworks 12, artist query and exhibitions 25, audio guide 2, vocabulary 100. 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; `"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), `public_domain_only`, `on_view_only`, and `has_image`, combined with AND
- Up to 12 rows per page (default 10), within the first 1,000 matches; `sort` is `relevance`, `date_asc`, or `date_desc`, and `sort_applied` reports `popularity` when relevance had no query text
- `facets` adds the top 15 values for up to seven fields (`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 10 are fetched; `sections` chooses from description and provenance (default), exhibition_history, publication_history, and catalogue
- Records return in request order. `missing_ids` lists ids the museum doesn't have; `deferred_ids` lists records held back by the response budget plus ids not yet tried, to pass to the same tool again
- `include_related_media` (default on) loads up to 20 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 25 are fetched. Query mode adds `artists_only` (default `true`), `born_from` / `born_to`, and up to 25 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 25 per page within the first 1,000 matches
- 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)
- 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); up to two 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 100 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, 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
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.
- 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.
- 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.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessResponsive