readwise_list_books
Retrieve books with highlights from Readwise, filter by category, source, or date to organize your reading materials.
Instructions
List books that have highlights in Readwise with optional filtering
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page_size | No | Number of results per page (default: 100, max: 1000) | |
| page | No | Page number for pagination | |
| category | No | Filter books by category | |
| source | No | Filter books by source | |
| updated__lt | No | Filter books updated before this date (ISO 8601) | |
| updated__gt | No | Filter books updated after this date (ISO 8601) | |
| last_highlight_at__lt | No | Filter books with last highlight before this date (ISO 8601) | |
| last_highlight_at__gt | No | Filter books with last highlight after this date (ISO 8601) |
Implementation Reference
- The handleListBooks function implements the core logic for the readwise_list_books tool. It initializes the Readwise client, maps input arguments to API parameters, calls the Readwise API's listBooks method, processes the response to include essential fields only, and returns the result as MCP-formatted content.
export async function handleListBooks(args: any) { const client = await initializeClient(); const params = { page_size: args.page_size, page: args.page, category: args.category, source: args.source, updated__lt: args.updated__lt, updated__gt: args.updated__gt, last_highlight_at__lt: args.last_highlight_at__lt, last_highlight_at__gt: args.last_highlight_at__gt, }; const response = await client.listBooks(params); // Strip to essentials const minimal = { count: response.data.count, results: response.data.results.map(b => ({ id: b.id, title: b.title, author: b.author, category: b.category, num_highlights: b.num_highlights })) }; return { content: [ { type: 'text', text: JSON.stringify(minimal, null, 2), }, ], }; } - Defines the tool schema including name, description, and detailed inputSchema with properties for pagination, filtering by category/source/date, matching the handler parameters.
{ name: 'readwise_list_books', description: 'List books that have highlights in Readwise with optional filtering', inputSchema: { type: 'object', properties: { page_size: { type: 'number', description: 'Number of results per page (default: 100, max: 1000)', }, page: { type: 'number', description: 'Page number for pagination', }, category: { type: 'string', enum: ['books', 'articles', 'tweets', 'supplementals', 'podcasts'], description: 'Filter books by category', }, source: { type: 'string', description: 'Filter books by source', }, updated__lt: { type: 'string', description: 'Filter books updated before this date (ISO 8601)', }, updated__gt: { type: 'string', description: 'Filter books updated after this date (ISO 8601)', }, last_highlight_at__lt: { type: 'string', description: 'Filter books with last highlight before this date (ISO 8601)', }, last_highlight_at__gt: { type: 'string', description: 'Filter books with last highlight after this date (ISO 8601)', }, }, additionalProperties: false, }, }, - src/handlers/index.ts:51-52 (registration)In the main handleToolCall dispatcher, the 'readwise_list_books' case routes tool calls to the handleListBooks handler function.
case 'readwise_list_books': return handleListBooks(args);