readwise_search_highlights

Search across all highlights using text queries and field-specific filters to find specific content in your Readwise library.

Instructions

Advanced search across all highlights using text queries and field-specific filters. Equivalent to official Readwise MCP search functionality.

Input Schema

TableJSON Schema

Name	Required	Description
`textQuery`	No	Main text to search for across all highlight content (like vector_search_term)
`fieldQueries`	No	Specific field searches (like full_text_queries)
`bookId`	No	Filter results to specific book
`limit`	No	Maximum number of results to return

Implementation Reference

src/handlers/highlights-handlers.ts:163-192 (handler)

The core handler function that executes the tool logic: initializes the Readwise client, maps arguments to search parameters, calls client.searchHighlights(), processes results, and returns formatted JSON.

export async function handleSearchHighlights(args: any) {
  const client = await initializeClient();
  
  const params = {
    textQuery: args.textQuery,
    fieldQueries: args.fieldQueries,
    bookId: args.bookId,
    limit: args.limit,
  };
  
  const response = await client.searchHighlights(params);
  
  // Strip to essentials
  const minimal = response.data.map(result => ({
    text: result.highlight.text,
    note: result.highlight.note || undefined,
    book: result.book.title,
    author: result.book.author,
    score: result.score
  }));
  
  return {
    content: [
      {
        type: 'text',
        text: JSON.stringify(minimal, null, 2),
      },
    ],
  };
}

src/tools/tool-definitions.ts:385-425 (schema)

Tool definition including name, description, and input schema for parameter validation.

{
  name: 'readwise_search_highlights',
  description: 'Advanced search across all highlights using text queries and field-specific filters. Equivalent to official Readwise MCP search functionality.',
  inputSchema: {
    type: 'object',
    properties: {
      textQuery: {
        type: 'string',
        description: 'Main text to search for across all highlight content (like vector_search_term)',
      },
      fieldQueries: {
        type: 'array',
        items: {
          type: 'object',
          properties: {
            field: {
              type: 'string',
              enum: ['document_title', 'document_author', 'highlight_text', 'highlight_note', 'highlight_tags'],
              description: 'Field to search in',
            },
            searchTerm: {
              type: 'string',
              description: 'Term to search for in the specified field',
            },
          },
          required: ['field', 'searchTerm'],
        },
        description: 'Specific field searches (like full_text_queries)',
      },
      bookId: {
        type: 'number',
        description: 'Filter results to specific book',
      },
      limit: {
        type: 'number',
        description: 'Maximum number of results to return',
      },
    },
    additionalProperties: false,
  },
},

src/handlers/index.ts:57-58 (registration)
Dispatches calls to the 'readwise_search_highlights' tool to the appropriate handler function via switch case.
```
case 'readwise_search_highlights':
  return handleSearchHighlights(args);
```
src/index.ts:24-26 (registration)
Registers the full tools list (including readwise_search_highlights schema) for MCP ListTools requests.
```
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return { tools };
});
```

src/index.ts:28-33 (registration)

Sets up the MCP CallTool handler that routes to handleToolCall based on tool name.

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  try {
    return await handleToolCall(name, args);
  } catch (error) {

Readwise MCP Enhanced