# aspen-catalog-mcp

An MCP (Model Context Protocol) server for searching [Aspen Discovery](https://github.com/Aspen-Discovery/aspen-discovery) library catalogs. Use it with Claude, or any MCP-compatible AI client, to check if your local library carries a book before recommending it.

## What it does

- **`search_catalog`** — Search the library catalog by keyword, title, author, subject, or ISBN
- **`check_availability`** — Check a list of book titles against the catalog, so AI recommendations can be filtered to books your library actually has

## Setup

### 1. Get API access from your library

Aspen Discovery supports two access methods:

- **IP allow-listing** (recommended) — Ask your library to add your server's IP to the Aspen Discovery API allow-list. No credentials needed.
- **API token pair** — Some libraries may issue API key pairs used by the Aspen LiDA mobile app.

Your library also needs to allow your IP through any CDN/firewall (e.g. Cloudflare) in front of the catalog.

### 2. Install

```bash
npm install -g aspen-catalog-mcp
```

Or clone and build from source:

```bash
git clone https://github.com/ecmulli/aspen-catalog-mcp.git
cd aspen-catalog-mcp
npm install
npm run build
```

### 3. Configure

Set the required environment variable:

```bash
export ASPEN_BASE_URL="https://catalog.faylib.org"  # your library's Aspen catalog URL
```

If using token auth, also set:

```bash
export ASPEN_API_KEY1="your-key-1"
export ASPEN_API_KEY2="your-key-2"
```

### 4. Add to Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "library-catalog": {
      "command": "npx",
      "args": ["-y", "aspen-catalog-mcp"],
      "env": {
        "ASPEN_BASE_URL": "https://catalog.faylib.org"
      }
    }
  }
}
```

Or if running from source:

```json
{
  "mcpServers": {
    "library-catalog": {
      "command": "node",
      "args": ["/path/to/aspen-catalog-mcp/dist/index.js"],
      "env": {
        "ASPEN_BASE_URL": "https://catalog.faylib.org"
      }
    }
  }
}
```

## Finding your library's Aspen catalog URL

Many public libraries use Aspen Discovery. The catalog URL is typically:

- `https://catalog.yourlibrary.org`
- `https://yourlibrary.aspendiscovery.org`

You can check if your library uses Aspen Discovery by looking for "Powered by Aspen Discovery" in the footer of their online catalog.

## How it works

This server talks to the [Aspen Discovery SearchAPI](https://github.com/Aspen-Discovery/aspen-discovery/blob/main/code/web/services/API/SearchAPI.php), specifically the `searchLite` method, which returns catalog records matching a search query.

## License

MIT