LibraryMCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@LibraryMCP search for science fiction books available for loan"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 documentationPrerequisites
Installation
Clone the repository:
git clone <repository-url> cd libraryMCPInstall dependencies:
uv syncConfigure credentials in
.env(copy from.envand 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 --reloadThe 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/tokenfirst to get a token, then paste it in the Bearer fieldReDoc: 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.pySimple Frontend Demo (optional)
You can interact with the API using a tiny frontend:
Open
frontend/index.htmlin your browserEnsure 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.pyThe 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 by title, author, or genre |
| Get full details of a book by ID |
| Add a new book to the catalog |
| Update book metadata or copy count |
| Remove a book (blocked if active loans exist) |
| List members with optional filters |
| Register a new library member |
| Get member profile, loan history, and fines |
| Delete a member (blocked if active loans or unpaid fines) |
| Borrow a book for a member |
| Return a borrowed book, calculating any overdue fine |
| List all active loans for a member |
| 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 (initialavailable_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 toolsadd_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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
Read-only MCP server exposing a user ORANO library to their own AI agent.
MCP server for searching Airweave collections with natural language queries.
An MCP server that provides congressional transcripts
Related MCP Servers
- FlicenseAqualityDmaintenanceAn 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-
- AlicenseBqualityDmaintenanceMCP server that enables searching books by author via Open Library API and searching keywords inside local text files.2ISC
- FlicenseAqualityDmaintenanceA 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-
- AlicenseNot gradedqualityDmaintenanceMCP server for querying HyRead ebook collections across 41 Taiwan public libraries, enabling search, book details, and library availability checks via natural language.MIT