Readwise Reader MCP Server

Instructions

Implementation Reference

• src/handlers/tag-search-handlers.ts:24-73 (handler)

  MCP tool handler that extracts search terms from args, calls client.searchDocumentsByTopic, formats results as JSON, appends messages if any, and returns text content response.
  export async function handleTopicSearch(args: any) { const client = initializeClient(); const { searchTerms } = args as { searchTerms: string[] }; const response = await client.searchDocumentsByTopic(searchTerms); const searchResults = { searchTerms, totalMatches: response.data.length, documents: response.data.map((doc: any) => ({ id: doc.id, url: doc.url, title: doc.title, author: doc.author, source: doc.source, category: doc.category, location: doc.location, tags: doc.tags, site_name: doc.site_name, word_count: doc.word_count, created_at: doc.created_at, updated_at: doc.updated_at, published_date: doc.published_date, summary: doc.summary, image_url: doc.image_url, source_url: doc.source_url, notes: doc.notes, reading_progress: doc.reading_progress, first_opened_at: doc.first_opened_at, last_opened_at: doc.last_opened_at, saved_at: doc.saved_at, last_moved_at: doc.last_moved_at, })) }; let responseText = JSON.stringify(searchResults, null, 2); if (response.messages && response.messages.length > 0) { responseText += '\n\nMessages:\n' + response.messages.map(msg => `${msg.type.toUpperCase()}: ${msg.content}`).join('\n'); } return { content: [ { type: 'text', text: responseText, }, ], }; }
• src/tools/tool-definitions.ts:155-171 (schema)

  Tool schema definition with name, description, and inputSchema specifying searchTerms array.
  { name: 'readwise_topic_search', description: 'Search documents in Readwise Reader by topic using regex matching on title, summary, notes, and tags', inputSchema: { type: 'object', properties: { searchTerms: { type: 'array', items: { type: 'string' }, description: 'List of search terms to match against document content (case-insensitive regex matching)', minItems: 1, }, }, required: ['searchTerms'], additionalProperties: false, }, },
• src/readwise-client.ts:212-263 (helper)

  Core search logic in ReadwiseClient: paginates all documents, filters client-side using case-insensitive regex on title/summary/notes/tags for any matching search term.
  async searchDocumentsByTopic(searchTerms: string[]): Promise<APIResponse<ReadwiseDocument[]>> { try { // Fetch all documents without full content for performance const allDocuments: ReadwiseDocument[] = []; let nextPageCursor: string | undefined; do { const params: ListDocumentsParams = { withFullContent: false, withHtmlContent: false, }; if (nextPageCursor) { params.pageCursor = nextPageCursor; } const response = await this.listDocuments(params); allDocuments.push(...response.data.results); nextPageCursor = response.data.nextPageCursor; } while (nextPageCursor); // Create regex patterns from search terms (case-insensitive) const regexPatterns = searchTerms.map(term => new RegExp(term.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i') ); // Filter documents that match any of the search terms const matchingDocuments = allDocuments.filter(doc => { // Extract searchable text fields const searchableFields = [ doc.title || '', doc.summary || '', doc.notes || '', // Handle tags - they can be string array or object Array.isArray(doc.tags) ? doc.tags.join(' ') : '', ]; const searchableText = searchableFields.join(' ').toLowerCase(); // Check if any regex pattern matches return regexPatterns.some(pattern => pattern.test(searchableText)); }); return this.createResponse(matchingDocuments); } catch (error) { if (error instanceof Error && error.message.startsWith('RATE_LIMIT:')) { const seconds = parseInt(error.message.split(':')[1], 10); throw new Error(`Rate limit exceeded. Too many requests. Please retry after ${seconds} seconds.`); } throw error; } }
• src/handlers/index.ts:9-32 (registration)

  Tool dispatcher function with switch case registering/routing readwise_topic_search to its handler.
  export async function handleToolCall(name: string, args: any) { switch (name) { case 'readwise_save_document': return handleSaveDocument(args); case 'readwise_list_documents': return handleListDocuments(args); case 'readwise_update_document': return handleUpdateDocument(args); case 'readwise_delete_document': return handleDeleteDocument(args); case 'readwise_list_tags': return handleListTags(args); case 'readwise_topic_search': return handleTopicSearch(args); default: throw new Error(`Unknown tool: ${name}`); } }
• src/index.ts:24-26 (registration)

  MCP server registration of the tools list (including readwise_topic_search schema) for listTools requests.
  server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools }; });