harvard-library-mcp 0.1.1

MCP server for Harvard University Library catalog API

Harvard Library MCP Server

A Model Context Protocol (MCP) server for the Harvard University Library catalog API, providing comprehensive bibliographic search and metadata retrieval capabilities for AI assistants.

✨ Features

• 🔍 Comprehensive Search: Free-text search, advanced fielded search, collection-specific queries
• 📚 Rich Metadata: Native MODS XML format with structured JSON conversion
• 🔌 Universal Integration: stdio MCP transport for Claude Desktop, Cherry Studio, and other AI assistants
• ⚡ High Performance: Async HTTP client with built-in rate limiting and error handling
• 🌐 Access to 20M+ Records: Search Harvard's entire academic library collection
• 📖 Complete Metadata: Access to bibliographic records, subject headings, and collection information

🚀 Quick Start

Installation from PyPI

pip install harvard-library-mcp

Usage with AI Assistants

Cherry Studio Integration

Cherry Studio provides native MCP server support for seamless integration with the Harvard Library catalog.

Prerequisites:

• Cherry Studio installed on your system
• harvard-library-mcp package installed via pip install harvard-library-mcp

Step 1: Install MCP Environment

1. Open Cherry Studio → Settings → MCP Server
2. Click "Install" to automatically install required dependencies
3. If installation fails, manually install to the Cherry Studio directory:
   • Windows: C:\Users\{username}\.cherrystudio\bin
   • macOS/Linux: ~/.cherrystudio/bin

Step 2: Configure Harvard Library MCP Server Cherry Studio may use the standard MCP configuration format. Add the following to your Cherry Studio MCP settings:

{
  "mcp": {
    "servers": {
      "harvard-library": {
        "command": "uvx",
        "args": ["harvard-library-mcp"],
        "env": {}
      }
    }
  }
}

Step 3: Start Using

1. Restart Cherry Studio
2. The Harvard Library tools will be available in your chat interface
3. Try queries like:
   • "Search for books about machine learning"
   • "Find works by Shakespeare in Harvard's collection"
   • "Show me records from the Harvard Fine Arts Library"

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcp": {
    "servers": {
      "harvard-library": {
        "command": "uvx",
        "args": ["harvard-library-mcp"]
      }
    }
  }
}

Configuration File Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Standard MCP Configuration

For any MCP-compatible client, use this JSON configuration format:

{
  "mcp": {
    "servers": {
      "harvard-library": {
        "command": "uvx",
        "args": ["harvard-library-mcp"],
        "env": {}
      }
    }
  }
}

Configuration Options:

• command: The command to run (uvx for running from PyPI packages)
• args: Package name and additional arguments (["harvard-library-mcp"])
• env: Environment variables for the server process (optional)

Example with custom settings:

{
  "mcp": {
    "servers": {
      "harvard-library": {
        "command": "uvx",
        "args": ["harvard-library-mcp"],
        "env": {
          "LOG_LEVEL": "DEBUG",
          "RATE_LIMIT_REQUESTS_PER_SECOND": "5"
        }
      }
    }
  }
}

Note: Using uvx harvard-library-mcp is the recommended approach as it automatically handles virtual environments and dependencies from PyPI.

Local Development

# Clone and install in development mode
git clone https://github.com/kltng/harvard-library-mcp.git
cd harvard-library-mcp
pip install -e .

# Run as MCP server (stdio)
python -m harvard_library_mcp.server

🛠️ Available MCP Tools

🔍 Search Tools

• search_catalog(query) - Free-text search across entire Harvard Library catalog
• search_by_title(title) - Search specifically by title field
• search_by_author(author) - Search by author/creator names
• search_by_subject(subject) - Search by subject headings and keywords
• advanced_search(filters) - Multi-field search with specific filters (title, author, subject, date, etc.)
• search_by_collection(collection_id) - Search within specific Harvard Library collections
• search_by_date_range(start_date, end_date) - Search by publication date range
• search_by_geographic_origin(location) - Search by publication location

📊 Utility Tools

• get_record_details(record_id) - Fetch complete bibliographic record by Harvard ID
• get_collections_list() - List all available collections with metadata
• parse_mods_metadata(mods_xml) - Convert MODS XML to structured JSON

📝 Usage Examples

Basic Search

Search for books about artificial intelligence published after 2020

Academic Research

Find works by Noam Chomsky in the linguistics collection
Show me details for Harvard record ID: 12345678

Collection Discovery

List all Harvard Library collections
Search within the Fine Arts Library collection for Renaissance art

⚙️ Configuration

Environment Variables

• HARVARD_API_BASE_URL: Base URL for Harvard Library API (default: https://api.lib.harvard.edu/v2)
• RATE_LIMIT_REQUESTS_PER_SECOND: API rate limit (default: 10)
• LOG_LEVEL: Logging level (default: INFO)

Advanced Configuration

For custom deployments, you can configure additional settings:

# Custom rate limiting
export RATE_LIMIT_REQUESTS_PER_SECOND=5

# Debug logging
export LOG_LEVEL=DEBUG

# Custom API endpoint (for development/testing)
export HARVARD_API_BASE_URL=https://api.lib.harvard.edu/v2

🏗️ Architecture

Core Components

• Server (server.py): MCP stdio interface implementation
• API Client (api/client.py): Async HTTP client for Harvard Library API
• Tools (tools/search_tools.py): MCP tool implementations
• Models (models/harvard_models.py): Pydantic models for data validation
• Configuration (config.py): Environment-based configuration management

Data Flow

AI Assistant → MCP Server → Harvard Library API → Bibliographic Records

The server handles:

• ✅ Rate limiting (10 req/sec default)
• ✅ Error handling and retries
• ✅ MODS XML parsing and JSON conversion
• ✅ Response validation and typing

👨‍💻 Development

Prerequisites

• Python 3.11 or higher
• Git

Setup Development Environment

# Clone the repository
git clone https://github.com/kltng/harvard-library-mcp.git
cd harvard-library-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with dependencies
pip install -e ".[dev]"

# Set up pre-commit hooks (optional)
pre-commit install

Running Tests

# Run all tests
make test
pytest tests/ -v

# Run tests with coverage
make test-coverage
pytest tests/ --cov=src --cov-report=html

# Run specific test categories
pytest tests/ -m unit        # Unit tests only
pytest tests/ -m integration # Integration tests only

Code Quality

# Run all linting checks
make lint
mypy src/
ruff check src/
black --check src/
isort --check-only src/

# Format code automatically
make format
black src/
isort src/
ruff check --fix src/

🐳 Docker Support

Build and Run

# Build Docker image
docker build -t harvard-library-mcp:latest .

# Run container
docker run -d --name harvard-library-mcp harvard-library-mcp:latest

# Using Docker Compose
docker-compose up -d
docker-compose logs -f

📦 Installation Options

From PyPI (Recommended)

pip install harvard-library-mcp

From Source

git clone https://github.com/kltng/harvard-library-mcp.git
cd harvard-library-mcp
pip install -e .

Development Version

pip install git+https://github.com/kltng/harvard-library-mcp.git

🔄 Release Process

This project uses automated releases with GitHub Actions and PyPI Trusted Publishing.

For Users

Install the latest version:

pip install harvard-library-mcp

Install a specific version:

pip install harvard-library-mcp==0.1.0

📄 License

MIT License - see LICENSE file for details.

🔗 Links & Resources

• PyPI Package: https://pypi.org/project/harvard-library-mcp/
• GitHub Repository: https://github.com/kltng/harvard-library-mcp
• Bug Reports: https://github.com/kltng/harvard-library-mcp/issues
• Harvard Library API Documentation:
  • LibraryCloud API
  • LibraryCloud Overview
• MODS XML Schema: http://www.loc.gov/standards/mods/

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📊 Project Statistics

• Total Records: 20M+ bibliographic records
• Collections: 100+ specialized library collections
• API Rate Limit: 10 requests/second (configurable)
• Response Formats: JSON, MODS XML
• Python Versions: 3.11, 3.12, 3.13
• License: MIT

---

⭐ Star this repository on GitHub if you find it useful!

Made with ❤️ for the academic research community