Skip to main content
Glama
LibraryMCP

LibraryMCP

by babosina

LibraryMCP

Demo project — Intended for local development and learning purposes only. Do not expose it to the public internet or use it to store real data.

LibraryMCP is a FastAPI-based backend server designed to serve as a Model Context Protocol (MCP) tool invocation source for library management. It provides a set of API endpoints to manage books, members, and loans in a library system.

Features

  • Books Management: Full CRUD with filtering by title, author, genre, and availability.

  • Members Management: Register, list (with filters), view details with loan history and fines, update, and delete with business rules.

  • Loans Management: Borrow/return workflows, active loans listing, and fine calculations.

  • JWT Authentication: All API endpoints (except /auth/token) require a Bearer token. Credentials are configurable via environment variables.

  • SQLite Database: Lightweight storage using SQLAlchemy ORM.

  • FastAPI: High-performance web framework for building APIs with Python.

  • CORS Enabled: Open CORS for easy local development and browser demos.

  • Simple Frontend Demo: Minimal HTML page to add/list books and members.

  • Seeding Tool: Built-in script to populate the database with initial sample data.

Related MCP server: MCP Open Library & File Search Server

Project Structure

libraryMCP/
├── backend/                # Application source code
│   ├── routers/            # API route handlers
│   │   ├── auth.py         # Authentication endpoint (token issuance)
│   │   ├── books.py        # Book-related endpoints
│   │   ├── loans.py        # Loan-related endpoints
│   │   └── members.py      # Member-related endpoints
│   ├── auth.py             # JWT creation, verification, and get_current_user dependency
│   ├── crud.py             # CRUD operations
│   ├── database.py         # Database configuration and session management
│   ├── main.py             # FastAPI application entry point (CORS + routers)
│   ├── models.py           # SQLAlchemy database models
│   ├── schemas.py          # Pydantic models for request/response validation
│   └── seed.py             # Database seeding script
├── frontend/
│   └── index.html          # Simple browser demo (books/members)
├── library.db              # SQLite database file
├── openapi.json            # Generated OpenAPI schema snapshot
├── pyproject.toml          # Project dependencies and configuration
├── uv.lock                 # Lock file for dependencies
└── README.md               # Project documentation

Prerequisites

  • Python >= 3.13

  • uv (recommended for dependency management)

Installation

  1. Clone the repository:

    git clone <repository-url>
    cd libraryMCP
  2. Install dependencies:

    uv sync
  3. Configure credentials in .env (copy from .env and fill in your values):

    ADMIN_USERNAME="admin"
    ADMIN_PASSWORD="your-password"
    SECRET_KEY="your-secret-key"
    BACKEND_URL=http://localhost:8000

Usage

Running the Server

Start the FastAPI server using uvicorn:

uv run uvicorn backend.main:app --reload

The API will be available at http://127.0.0.1:8000.

Authentication

All endpoints except POST /auth/token require a JWT Bearer token.

Obtain a token:

curl -X POST http://127.0.0.1:8000/auth/token \
  -d "username=admin&password=your-password"

Response:

{ "access_token": "<token>", "token_type": "bearer" }

Use the token:

curl http://127.0.0.1:8000/books/ \
  -H "Authorization: Bearer <token>"

Tokens expire after 30 minutes. Configure credentials via ADMIN_USERNAME, ADMIN_PASSWORD, and SECRET_KEY environment variables (or in .env).

API Documentation

Once the server is running, you can access the interactive API documentation:

Seeding the Database

To populate the database with sample data, run the seed script:

uv run python backend/seed.py

Simple Frontend Demo (optional)

You can interact with the API using a tiny frontend:

  • Open frontend/index.html in your browser

  • Ensure the backend runs at http://localhost:8000 (CORS is enabled)

  • Use the UI to add/list books and members

MCP Server

The MCP server exposes the library's functionality as tools that AI assistants (Claude, etc.) can call directly.

Running the MCP Server

The MCP server communicates over stdio. Start the FastAPI backend first, then run:

uv run python mcp_server/main_stdio.py

The server reads BACKEND_URL, ADMIN_USERNAME, and ADMIN_PASSWORD from the environment (or .env). It obtains a JWT token automatically on first use and refreshes it when it expires.

Connecting to Claude Desktop

Add the following to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "library": {
      "command": "uv",
      "args": ["run", "python", "mcp_server/main_stdio.py"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/libraryMCP"
      }
    }
  }
}

Available MCP Tools

Tool

Description

search_books

Search books by title, author, or genre

get_book

Get full details of a book by ID

add_book

Add a new book to the catalog

update_book

Update book metadata or copy count

delete_book

Remove a book (blocked if active loans exist)

list_members

List members with optional filters

register_member

Register a new library member

get_member

Get member profile, loan history, and fines

delete_member

Delete a member (blocked if active loans or unpaid fines)

borrow_book

Borrow a book for a member

return_book

Return a borrowed book, calculating any overdue fine

get_loans

List all active loans for a member

check_fines

Get total outstanding fines for a member

API Endpoints Overview

Authentication

  • POST /auth/token — Obtain a JWT Bearer token (form fields: username, password).

Books

  • GET /books/ — List books with optional filters.

    • Query: title, author, genre, available_only

  • GET /books/{id} — Get a single book by ID.

  • POST /books/ — Create a book (initial available_copies = total_copies).

  • PUT /books/{id} — Update a book.

  • DELETE /books/{id} — Delete a book (blocked if there are active loans).

Members

  • GET /members/ — List members with filters and pagination.

    • Query: skip, limit, name, email, is_active

  • GET /members/{id} — Get member details with loan history, active loans count, and total fines.

  • POST /members/ — Register a new member (unique email required).

  • PUT /members/{id} — Update member (cannot deactivate with active loans; email must be unique/valid).

  • DELETE /members/{id} — Delete member (blocked if active loans or unpaid fines).

Loans

  • POST /loans/borrow — Borrow a book (member must be active; book must have available copies; no duplicate active loan).

  • POST /loans/return — Return a book (increments availability; computes fine if overdue: $0.50/day).

  • GET /loans/{member_id} — List active loans for a member.

  • GET /loans/{member_id}/fines — Calculate and return fine breakdown for a member.

Available Tools

13 tools
add_bookC

Adds a new book to the library catalog. ISBN must be unique.

Inputs: isbn (required), title (required), author (required), genre, +1 more. Returns: result

borrow_bookA

Borrows a book for a member, creating a loan record. Fails if the book has no available copies or the member already has an active loan for it.

Inputs: book_id (required), member_id (required). Returns: result

check_finesA

Returns the total outstanding fines for a member, including overdue active loans and unpaid fines from returned books.

Inputs: member_id (required). Returns: result

delete_bookA

Removes a book from the catalog by book ID. Fails if the book has active loans.

Inputs: book_id (required). Returns: result

delete_memberA

Deletes a member account by member ID. Fails if the member has active loans or unpaid fines.

Inputs: member_id (required). Returns: result

get_bookB

Retrieves full details of a single book by its ID.

Inputs: book_id (required). Returns: result

get_loansA

Lists all active (not yet returned) loans for a member by member ID.

Inputs: member_id (required). Returns: result

get_memberA

Retrieves a member's profile, loan history, and outstanding fines by member ID.

Inputs: member_id (required). Returns: result

list_membersA

Lists all library members with optional filters by name, email, or active status.

Inputs: name, email, is_active. Returns: result

register_memberA

Registers a new library member with a name and email address. Email must be unique.

Inputs: name (required), email (required). Returns: result

return_bookA

Returns a borrowed book for a member, closing the loan and calculating any overdue fines ($0.50/day). Fails if no active loan exists for the member and book.

Inputs: book_id (required), member_id (required). Returns: result

search_booksA

Searches for books in the library by title, author, or genre. Returns matching books with their availability status.

Inputs: genre, title, author, available_only. Returns: result

update_bookA

Updates book metadata or copy count by book ID. Only provided fields are updated.

Inputs: book_id (required), isbn, genre, title, +3 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: book catalog, member management, loans, and fines form separate clusters. The main overlap is that get_member includes loan history and outstanding fines, which also have dedicated tools, but the descriptions are clear enough to avoid serious confusion.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern, such as get_book, update_book, borrow_book, and list_members. There are no mixed conventions or vague generic verbs, making the API predictable.

    Tool Count5/5

    13 tools is well-scoped for a library management domain, covering books, members, loans, and fines without excessive granularity. Each tool represents a meaningful operation that earns its place in the set.

    Completeness3/5

    Book catalog coverage is solid, and borrow/return/fine-check workflows are present. However, there is no update_member tool, and fines can only be checked, never paid or cleared, leaving an unresolved state for members with unpaid fines.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      An MCP server for managing local Calibre libraries using the calibredb CLI. It allows users to search books, manage metadata, and retrieve EPUB file paths through natural language commands.
      7
      -
    • F
      license
      A
      quality
      D
      maintenance
      A small MCP server modeling a library with tools to search books, borrow books, and manage members, enabling interaction with a library catalog through natural language.
      4
      -