library_find

LibraryRead-only

Find items and folders in the library. Items carry id: hold on to it, not the path, which changes when AI rename lands. type is one vocabulary for every action: image, video, audio, document, pdf, font, bookmark, slideshow, scancode, video_loop, screen_recording, recordings.

Available at every access level, including a client that sent X-Access-Level: readonly.

Parameters

Name	Type	Required	Description
action	string one of "list", "search", "get", "folders", "tags", "linked", "stats", "trash", "duplicates"	yes	What to do. list: Items, newest first. (type, folder, folder_id, unread, oldest_first, skip, take) search: Items matching words or a colour, as the gallery's search bar finds them. (query, type, folder, folder_id, unread, oldest_first, skip, take) get: One item in full: text, tags, folder, size, capture context. (id, path) folders: The folders, with ids, paths, counts and tree. tags: Every tag with its count. linked: The linked external folders. stats: Counts by type, trash and total. trash: The Trash, most recently trashed first. (skip, take) duplicates: Duplicate groups: one item each, with duplicate_count. (query, skip, take)
query	string	no	Words, or a colour ('#ff0000', '#red', 'rgb(…)'), as typed in the search bar.
type	string one of "image", "video", "audio", "document", "pdf", "font", "bookmark", "slideshow", "scancode", "video_loop", "screen_recording", "recordings"	no	Only items of this type.
folder	string	no	Only this folder and its subfolders: a rel path from folders ('' = the save root, 'Reader' = the reader root) or a linked folder's absolute path.
folder_id	integer	no	Instead of folder: a folder's id from folders.
unread	boolean	no	Only items not yet opened.
oldest_first	boolean	no	Oldest first instead of newest.
id	string	no	An item's id.
path	string	no	Or an item's path or name.
skip	integer	no	Items to skip.
take	integer	no	Items to return (default 50).

Example

A JSON-RPC call to POST http://localhost:21516/mcp with the bearer token, filling in the required parameters:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "library_find",
    "arguments": {
      "action": "list"
    }
  }
}

See the MCP server overview for how to connect a client and where the token lives.