How to Use the Calibre-Web MCP in Pydantic AI

Query Calibre-Web libraries and sync Kobo devices with strict type-safety using Pydantic AI.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Calibre-Web MCP to Pydantic AI

Create your Vinkius account to connect Calibre-Web to Pydantic AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Calibre-Web with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Parse Calibre-Web catalogs using Pydantic AI

Your Pydantic AI agent uses the `get_opds_catalog` tool to fetch your library's main catalog feed. The tool returns structured XML or JSON data, which the framework immediately validates against strict type schemas before your model ever reads it. This means if your Calibre-Web instance returns unexpected catalog structures, the agent fails instantly with a validation error. You get total type safety and zero silent failures during library processing.

Fetch shelf structures with this MCP Server

The `get_opds_shelf` tool pulls specific shelf contents into your Pydantic AI agent. Every book, author, and category field returned from the shelf is parsed and verified against your Pydantic models at runtime. If a book is missing a required title or ID field, the framework catches the error immediately. This guarantees your agent never operates on corrupted or incomplete shelf data.

Secure Kobo syncs with strict type validation

The `sync_kobo_library` tool runs Kobo library updates directly from your Pydantic AI agent. This MCP tool validates your Kobo Token before executing the tool, preventing malformed tokens from hitting the API. Because the framework is model-agnostic, you can trigger this sync using OpenAI, Anthropic, or local models. The toolset configuration ensures the sync payload matches the expected schema every time.

Setup guide

Set up Calibre-Web MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "calibre-web-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to Calibre-Web tools.",
)

result = await agent.run("List recent Calibre-Web transactions")
print(result.output)

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Calibre-Web. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Calibre-Web now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Calibre-Web MCP in Pydantic AI

You connect to the Calibre-Web MCP Server using the MCPToolset class with your server's HTTP endpoint. Then, pass this toolset into the toolsets argument when initializing your Pydantic AI agent.

The framework raises a validation error immediately. Pydantic AI ensures that every piece of book metadata matches your defined schemas, preventing silent corruption.

Yes. You can connect your Pydantic AI agent to the Calibre-Web MCP Server using either SSE or Streamable HTTP transports.

No. The server runs externally on Vinkius, and your Pydantic AI agent connects to it via a secure, hosted endpoint.

Your book metadata, catalog feeds, and Kobo sync tokens are processed in an ephemeral V8 sandbox. This MCP Server does not store your library data or tokens, ensuring your reading history and authentication credentials remain completely private.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript