Library MCP

A Model Context Protocol (MCP) server for college library management. This server provides AI-powered tools for managing library operations including book issuance, returns, inventory, and reporting.

Features

Tools

• Issue Book: Issue an available copy of a book to a student
• Process Return: Return a book and automatically assess late fines if overdue
• Add Book: Add new titles to the library catalog with multiple copies

Resources

• Book Info: Retrieve full details for any book in the catalog
• Book ID Lookup: Resolve partial titles to matching book IDs
• Availability: Check available vs total copies of any book

Prompts

• Returns Due Today: Generate reminder messages for books due back today
• Top Performing Books: Report the most-issued books
• Under-Performing Books: Identify underutilized titles for promotion or retirement

Requirements

• Python 3.12+
• MySQL 8.0+
• FastMCP 3.4.7

Installation

1. Clone the repository:

git clone <repository-url>
cd library_mcp

2. Install dependencies:

uv sync

3. Set up MySQL database:

mysql -u root -p < data/library_schema.sql
mysql -u root -p < data/library_seed.sql

Or let the application auto-initialize on first run.

Configuration

Set these environment variables in .env:

MYSQL_HOST=localhost
MYSQL_USERNAME=root
MYSQL_PASSWORD=rootpassword
MYSQL_DATABASE=library

Running the Server

uv run main.py

The MCP server will start on http://127.0.0.1:19000/mcp

Database Auto-Initialization

The server automatically initializes the MySQL database on first run:

• Creates the library database and all tables
• Populates seed data with sample users, books, and transactions
• Subsequent runs skip initialization if tables already exist

Project Structure

library_mcp/
├── main.py              # MCP server entry point with tools, resources, and prompts
├── db.py                # Database connection and initialization utilities
├── operations.py        # Business logic for library operations
├── datastore.py         # Data access layer
├── test.py              # Database connection test
├── pyproject.toml       # Project configuration and dependencies
├── README.md            # This file
├── .gitignore           # Git ignore rules
└── data/
    ├── library_schema.sql    # Database schema (tables and structure)
    └── library_seed.sql      # Sample data (users, books, transactions)

Database Schema

The library system manages:

• Users: Librarians and students with authentication
• Books: Catalog with metadata (ISBN, title, subject, publisher)
• Book Copies: Individual copies with status tracking
• Loan Transactions: Issue and return records with dates
• Fines: Late fee assessment and payment tracking
• Authors & Publishers: Reference data for cataloging

API Usage

Issuing a Book

issue_book(student_id="STU001", book_id=1, date="2026-08-13")

Returning a Book

process_return(student_id="STU001", book_id=1, date="2026-08-20", description="")

Adding a New Book

add_book(title="New Title", isbn13="978-0-123456-78-9", subject="CS", copies=5)

Getting Book Info

GET /resources/book://{book_id}

Checking Availability

GET /resources/availability://{book_id}

Testing

Run the test script to verify database connectivity:

uv run test.py

License

MIT