OpenLibrary MCP

A book search application that provides access to the OpenLibrary API through both FastAPI and MCP (Model Context Protocol) servers.

🚀 Features

• Book Search: Search for books using the OpenLibrary API

• Dual Server Support: Available as both FastAPI web server and MCP server

• Data Validation: Robust Pydantic models with proper validation

• Error Handling: Graceful handling of incomplete API responses

• Comprehensive Logging: Detailed logging for monitoring and debugging

• Code Quality: Pre-commit hooks for maintaining code standards

Related MCP server: ScholarScope MCP

📦 Installation

Prerequisites

• Python 3.11+

• Poetry (recommended) or pip

Using Poetry (Recommended)

# Clone the repository
git clone <repository-url>
cd openlibrary_mcp

# Install dependencies
poetry install

# Install pre-commit hooks
poetry run pre-commit install

# Activate virtual environment
poetry shell

Using pip

# Clone the repository
git clone <repository-url>
cd openlibrary_mcp

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

# Install dependencies
pip install -r requirements.txt

🛠️ Usage

FastAPI Server

Start the FastAPI web server:

python -m openlibrary_mcp.fastapi_server

The server will be available at http://localhost:8000

API Endpoints

• GET /search?query=<search_term> - Search for books

• GET /health - Health check endpoint

• GET / - API information

• GET /docs - Interactive API documentation

Example:

curl "http://localhost:8000/search?query=python+programming"

MCP Server

The MCP server provides tool-based access for AI assistants:

python -m openlibrary_mcp.mcp_server

Or use the installed command:

openlibrary-mcp

🤖 Using with Claude Desktop

This MCP server can be easily integrated with Claude Desktop to provide book search capabilities directly in your conversations with Claude.

📋 Prerequisites

• Claude Desktop application installed

• This openlibrary_mcp project installed and working

• Poetry or Python environment set up

⚙️ Setup Instructions

1. Locate Claude Desktop Config

Find your Claude Desktop configuration file:

macOS:

~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

2. Add Books MCP Server

Edit the claude_desktop_config.json file and add the openlibrary-mcp server:

{
  "mcpServers": {
    "books-search": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/uysalserkan/openlibrary-mcp",
        "openlibrary-mcp"
      ]
    },
    ...
  }
}

3. Restart Claude Desktop

Close and restart Claude Desktop for the changes to take effect.

🎯 Using the Book Search Tool

Once configured, you can use the book search functionality in Claude Desktop:

Example Conversations:

You: "Can you help me find books about Python programming?"

Claude: I'll search for Python programming books for you.

[Claude uses the search_books tool]

Claude: I found several Python programming books:

1. "Learning Python" by Mark Lutz (2013)

   • 5 editions available

   • Language: English

2. "Python Crash Course" by Eric Matthes (2019)

   • 3 editions available

   • Language: English

[...more results...]

Other Example Queries:

• "Find books by J.R.R. Tolkien"

• "Search for books about machine learning"

• "Look up George Orwell's 1984"

• "Find cookbooks published after 2020"

🔧 Tool Details

The MCP server provides one tool:

search_books(query: str)

• Purpose: Search for books using OpenLibrary API

• Input: Search query string

• Output: Structured book data including titles, authors, publication years, and more

• Examples:

  • "python programming"

  • "tolkien lord of the rings"

  • "george orwell 1984"

✅ Verification

After setup, you should see:

1. In Claude Desktop: The openlibrary-mcp server listed in available tools

2. In Conversations: Ability to ask Claude to search for books

3. In Logs: MCP server startup messages when Claude Desktop starts

The integration allows Claude to seamlessly search for books and provide detailed information about authors, publication years, editions, and more, making it a powerful research and discovery tool!

🔧 Development

Pre-commit Hooks

This project uses pre-commit hooks to ensure code quality and consistency. The following tools are configured:

🛡️ Code Quality Tools

• Black: Code formatting (line length: 88)

• isort: Import sorting with black compatibility

• Ruff: Fast Python linter (replaces flake8)

• mypy: Static type checking

• Bandit: Security vulnerability scanner

📝 General Checks

• Trailing whitespace: Automatically removes trailing spaces

• End of file: Ensures files end with newline

• YAML/TOML validation: Validates configuration files

• Large files: Prevents committing large files

• Merge conflicts: Detects merge conflict markers

• Debug statements: Finds debug statements in code

🚀 Running Pre-commit

# Install hooks (run once)
poetry run pre-commit install

# Run on all files
poetry run pre-commit run --all-files

# Run on specific files
poetry run pre-commit run --files openlibrary_mcp/models.py

# Skip hooks for a commit (not recommended)
git commit -m "message" --no-verify

⚙️ Tool Configuration

All tools are configured in pyproject.toml:

[tool.black]
line-length = 88
target-version = ['py311']

[tool.isort]
profile = "black"
line_length = 88

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "C4", "UP"]

[tool.mypy]
python_version = "3.11"
disallow_untyped_defs = true

📊 API Response Format

{
  "num_found": 1234,
  "q": "python programming",
  "docs": [
    {
      "author_name": "John Doe",
      "edition_count": 5,
      "first_publish_year": 2020,
      "language": "en",
      "title": "Python Programming Guide"
    }
  ]
}

🏗️ Project Structure

openlibrary_mcp/
├── openlibrary_mcp/           # Main package directory
│   ├── __init__.py      # Package initialization
│   ├── fastapi_server.py # FastAPI web server
│   ├── mcp_server.py    # MCP server implementation
│   ├── models.py        # Pydantic data models
│   └── providers.py     # OpenLibrary API provider
├── .pre-commit-config.yaml # Pre-commit configuration
├── claude_desktop_config.json # Sample Claude Desktop configuration
├── pyproject.toml       # Project configuration
├── poetry.lock          # Dependency lock file
├── README.md           # This file
└── dist/               # Built packages

🔧 Dependencies

• FastAPI: Web framework for building APIs

• FastMCP: MCP server implementation

• Pydantic: Data validation and settings management

• Uvicorn: ASGI server for FastAPI

• HTTPX: Async HTTP client for API calls

• Requests: HTTP library for synchronous requests

Development Dependencies

• pre-commit: Git hooks for code quality

• black: Code formatter

• isort: Import sorter

• ruff: Fast Python linter

• mypy: Static type checker

• bandit: Security linter

🔍 Data Models

BookDetails

Represents individual book information with optional fields to handle incomplete API responses:

• author_name: Author's name

• edition_count: Number of available editions

• first_publish_year: Year of first publication

• language: Book language(s)

• title: Book title

OpenLibrary

Represents the complete API response:

• num_found: Total number of books found

• q: Search query

• docs: List of book details

📋 Logging

The application includes comprehensive logging to help with monitoring and debugging:

🎯 Key Logging Features:

• API Calls: Track OpenLibrary API requests, responses, and timing

• Data Validation: Monitor model validation, data cleaning, and incomplete records

• Server Activity: Log server startup, endpoint access, and request processing

• Error Handling: Detailed error logging with context

📊 Log Levels:

• INFO: General application flow and important events

• DEBUG: Detailed validation steps and data processing

• WARNING: Non-critical issues (empty queries, missing fields)

• ERROR: Failures and exceptions with full context

🔧 Log Format:

2025-07-15 16:57:40,733 - openlibrary_mcp.providers - INFO - 📚 Starting book search for query: 'python'
2025-07-15 16:57:40,734 - openlibrary_mcp.models - INFO - ⚠️  1/3 books have missing critical fields

📝 Example Log Messages:

🔧 OpenLibraryProvider initialized with base_url: https://openlibrary.org
📚 Starting book search for query: 'python programming'
📡 API Response: 200 | Content-Length: 12345
✅ Search completed: 1234 total books found, 20 returned in response
🎯 Successfully processed 20 book records
🔍 MCP tool called: search_books with query='python'
🌐 GET /search - Query: {'query': 'python'}
📊 Response: 200 | Time: 0.523s

🧪 Testing

Run a quick test to verify the installation:

# Test FastAPI server
python -c "from openlibrary_mcp.providers import OpenLibraryProvider; print('✅ OpenLibrary provider works!')"

# Test models
python -c "from openlibrary_mcp.models import BookDetails, OpenLibrary; print('✅ Models imported successfully!')"

# Test pre-commit hooks
poetry run pre-commit run --all-files

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Ensure pre-commit hooks pass: poetry run pre-commit run --all-files

5. Add tests if applicable

6. Submit a pull request

Code Quality Standards

• Type hints: All functions must have proper type annotations

• Documentation: Use docstrings for all public functions and classes

• Error handling: Use proper exception chaining with raise ... from e

• Security: Avoid binding to all interfaces (0.0.0.0) in production

• Logging: Include meaningful log messages with appropriate levels

📝 License

This project is open source and available under the MIT License.

🔗 Related Links

• OpenLibrary API Documentation

• FastAPI Documentation

• MCP Documentation

• Pydantic Documentation

• Pre-commit Documentation

🐛 Issues

If you encounter any issues, please create an issue on the GitHub repository with:

• Description of the problem

• Steps to reproduce

• Expected vs actual behavior

• Your environment details