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: Lyceum

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:

• Swagger UI: http://127.0.0.1:8000/docs — click Authorize, call POST /auth/token first to get a token, then paste it in the Bearer field

• ReDoc: http://127.0.0.1:8000/redoc

• OpenAPI JSON: http://127.0.0.1:8000/openapi.json (a snapshot also lives at openapi.json)

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

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.