Luku API and MCP

Everything the web app and the iPhone app can do, over HTTP or through Claude. Your reading is yours: read it, write it, back it up, take it elsewhere.

Getting started

Mint a personal access token in Luku under Settings, API, choose read-only or read and write, and send it as a bearer token. That is the whole setup.

curl https://luku.app/api/v1/now \
  -H "Authorization: Bearer luku_pat_..."

The base URL is https://luku.app. A self-hosted Luku serves the same endpoints at its own address.

Authentication

Two credentials reach the same API. Both are stored hashed, carry a scope, and belong to one account.

CredentialPrefixSource
Personal access tokenluku_pat_Settings, API in the web app
OAuth access tokenluku_at_The OAuth flow below, used by Claude.ai

Scopes

A read token can read everything. Writing needs read write, and a read-only token asking to write is refused with 403 rather than quietly doing nothing.

OAuth 2.1

Luku is its own authorisation server, so signing a client in is the Luku login you already have: email, Google or Apple. There is no separate connector password.

GET  /.well-known/oauth-authorization-server
GET  /.well-known/oauth-protected-resource
POST /api/oauth/register     dynamic client registration (RFC 7591)
GET  /oauth/authorize        sign in, then approve what is being asked for
POST /api/oauth/token        PKCE S256, refresh rotation
POST /api/oauth/revoke

Authorisation codes last a minute and are single use, access tokens an hour, refresh tokens thirty days and rotate on use. Tokens are bound to https://luku.app/mcp as their audience, so one minted elsewhere is not accepted here.

MCP server

Luku speaks MCP at https://luku.app/mcp. In Claude.ai, go to Settings, Connectors, Add custom connector, and paste that URL. Leave the client ID and secret empty: Claude registers itself, sends you to the Luku sign-in page, and shows what it is asking for before anything is granted.

claude mcp add --transport http luku https://luku.app/mcp --scope user

Claude Code can skip the browser by sending a personal access token instead, or run luku-mcp over stdio.

Tools

36 tools. Read tools work with any token; write tools need a read-write one.

ToolDescriptionScope
luku_meThe reader, their settings and shelf sizesread
luku_libraryA shelf, or the whole libraryread
luku_bookOne book, with its sessions and bookmarksread
luku_nowWhat is being read right nowread
luku_sessionsReading sessions, by book or date rangeread
luku_statsMinutes, pages, books finished, goalsread
luku_monthly_statsOne month day by dayread
luku_goalsYearly and daily goalsread
luku_bookmarksSaved linksread
luku_search_booksSearch every source for a bookread
luku_book_infoMetadata for a book not in the libraryread
luku_find_coversCover candidatesread
luku_author_booksMore by the same authorread
luku_recommendationsRecommendations already generatedread
luku_exportThe library as JSON or markdownread
luku_changelogPublished changelog entriesread
luku_roadmapPlanned features and votesread
luku_add_bookAdd a book, metadata looked up for youwrite
luku_update_bookEdit metadata, rating or noteswrite
luku_set_statusMove a book between shelveswrite
luku_set_progressSet the position in page, percent or secondswrite
luku_delete_bookRemove a book and its sessionswrite
luku_start_timerStart readingwrite
luku_pause_timerPause readingwrite
luku_resume_timerResume readingwrite
luku_stop_timerStop, and carry the position onto the bookwrite
luku_log_sessionRecord reading that already happenedwrite
luku_edit_sessionCorrect a sessionwrite
luku_delete_sessionDelete a session and give back its progresswrite
luku_set_goalSet a yearly or daily goalwrite
luku_add_bookmarkSave a link to a bookwrite
luku_update_bookmarkEdit a saved linkwrite
luku_delete_bookmarkRemove a saved linkwrite
luku_set_settingsTheme, tracking method, recommendationswrite
luku_import_booksImport from a Bookshelf exportwrite
luku_vote_roadmapVote on the roadmapwrite

Account

Who the token belongs to, and the preferences that shape the apps.

GET/api/v1/meread

The reader, the token's scopes, and how many books sit on each shelf.

curl https://luku.app/api/v1/me \
  -H "Authorization: Bearer $LUKU_API_TOKEN"

GET/api/v1/settingsread

Theme, default tracking method and whether recommendations are on.

PATCH/api/v1/settingswrite

Change any of those.

Body

NameTypeDescription
themelight | dark | systemColour scheme
defaultTrackingMethodtime | pages | percentWhat a new book is tracked in
aiRecommendationsEnabledbooleanWhether recommendations are generated

Library

Books live on one of five shelves: reading, next-up, to-read, finished and abandoned. Lists are uncapped, so a request for a shelf returns the whole shelf.

GET/api/v1/libraryread

Every book, or one shelf of it.

Query

NameTypeDescription
statusstringLimit to one shelf
qstringMatch against title, subtitle and author
curl "https://luku.app/api/v1/library?status=reading" \
  -H "Authorization: Bearer $LUKU_API_TOKEN"

POST/api/v1/bookswrite

Add a book. Only the title is required: everything else is looked up the way the app looks it up when a book is added from search.

Body

NameTypeDescription
titlerequiredstringA trailing subtitle is split off
authorstringImproves the metadata lookup
statusstringDefaults to to-read
progressTypepages | percent | minutesDefaults to pages
enrichbooleanSet false to skip the lookup entirely
curl -X POST https://luku.app/api/v1/books \
  -H "Authorization: Bearer $LUKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "Piranesi", "author": "Susanna Clarke"}'

GET/api/v1/books/{id}read

One book in full.

PATCH/api/v1/books/{id}write

Edit metadata, rating or notes. Passing status moves the shelf and stamps the date that shelf is defined by.

DELETE/api/v1/books/{id}write

Remove a book and its sessions.

POST/api/v1/books/{id}/progresswrite

Move the reader's position. The percentage is derived, a book on the to-read shelf starts being read, and the start date is stamped the first time progress appears.

Body

NameTypeDescription
pagenumberFor a book tracked in pages
percentnumberFor one tracked in percent
secondsnumberFor an audiobook
curl -X POST https://luku.app/api/v1/books/$ID/progress \
  -H "Authorization: Bearer $LUKU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"page": 214}'

GET/api/v1/books/{id}/sessionsread

Every reading session for one book.

Reading and the timer

A session is the unit of reading. Starting one captures where the book stands; ending one carries the new position back onto the book. Paused time accumulates rather than being subtracted at the end, so a session paused twice still reports reading time and not wall clock.

GET/api/v1/nowread

The running or paused session, its elapsed time, and the reading shelf behind it.

GET/api/v1/users/{username}/nowpublic

Now reading, like a now playing feed: the book in the running or paused timer, or null, and the reading shelf. Needs no token and answers from any site, so a personal page can show it. Works when the reader's Currently reading is public, otherwise 403.

curl https://luku.app/api/v1/users/rolle/now

{
  "username": "rolle",
  "nowReading": {
    "state": "active",
    "kind": "book",
    "startedAt": "2026-11-03T17:05:00Z",
    "elapsedSeconds": 1260,
    "book": { "title": "...", "author": "...", "coverUrl": "https://..." }
  },
  "currentlyReading": [{ "title": "...", "author": "...", "coverUrl": "https://...", "lastRead": "..." }]
}

GET/api/v1/sessionsread

Sessions newest first.

Query

NameTypeDescription
bookIduuidOnly this book
sinceISO timestampStarted at or after
untilISO timestampStarted at or before

POST/api/v1/sessionswrite

Start a session. Passing endedAt writes a finished session in one call, which is how reading typed in after the fact gets logged.

Body

NameTypeDescription
bookIdrequireduuidThe book being read
startedAtISO timestampDefaults to now
endedAtISO timestampMakes this a finished session

GET/api/v1/sessions/activeread

The session that has not ended, if there is one.

PATCH/api/v1/sessions/{id}write

Edit a session, or end it. Passing endedAt, or finish: true, also carries the end position onto the book.

Body

NameTypeDescription
endPagenumberWhere the reading stopped
endPercentnumberFor a book tracked in percent
endSecondsnumberFor an audiobook

DELETE/api/v1/sessions/{id}write

Delete a session. A finished one takes the book's position back to what the remaining sessions account for.

PATCH/api/v1/sessions/{id}/timerwrite

Pause or resume a running session.

Body

NameTypeDescription
actionrequiredpause | resumeWhat to do

Statistics and goals

Totals derived from the same sessions the other endpoints serve.

GET/api/v1/statsread

Minutes and pages read today, this week, this month and this year, books finished, and the goals in force.

GET/api/v1/stats/monthlyread

One month, day by day.

Query

NameTypeDescription
yearnumberDefaults to this year
monthnumber1-12, defaults to this month

GET/api/v1/goalsread

Every year's goals.

PUT/api/v1/goalswrite

Set a year's goals. Pass null to clear one.

Body

NameTypeDescription
yearnumberDefaults to this year
yearlyBookGoalnumber | nullBooks to finish this year
dailyMinutesGoalnumber | nullMinutes to read a day

Bookmarks

Links saved against a book.

GET/api/v1/bookmarksread

Saved links, optionally for one book.

POST/api/v1/bookmarkswrite

Save a link.

Body

NameTypeDescription
bookIdrequireduuidThe book it belongs to
urlrequiredstringWhere it points
labelstringWhat to call it

PATCH/api/v1/bookmarks/{id}write

Edit a saved link.

DELETE/api/v1/bookmarks/{id}write

Remove a saved link.

Finding books

The same sources the app searches: Goodreads, Google Books, BookBeat, Open Library, Finna, the Internet Archive and Wikimedia.

GET/api/v1/searchread

Search for a book to add.

Query

NameTypeDescription
qrequiredstringAt least two characters

GET/api/v1/book-inforead

Description, page count, publisher, ISBNs and cover for one book.

Query

NameTypeDescription
titlestringTitle, or pass isbn
authorstringNarrows the match
isbnstringEither ISBN form

GET/api/v1/coversread

Cover candidates from every source, best guesses first.

GET/api/v1/author-booksread

Other books by the author of a Goodreads book page.

Query

NameTypeDescription
goodreadsUrlrequiredstringA book page on Goodreads
excludeTitlestringLeave this one out

GET/api/v1/recommendationsread

Recommendations already generated in the app.

Your data, in and out

Luku is a place to keep reading, not to trap it. The export is the whole library, and the import fills in what is already there rather than duplicating it.

GET/api/v1/export/{format}read

The whole library. Formats: json, csv, markdown, goodreads.

curl https://luku.app/api/v1/export/json \
  -H "Authorization: Bearer $LUKU_API_TOKEN" -o luku-backup.json

POST/api/v1/importwrite

Import books. A book already in the library gets its empty fields filled in, so a re-import never overwrites a correction made by hand.

Body

NameTypeDescription
csvstringContents of a Bookshelf CSV export
booksarrayParsed rows, instead of csv

The app itself

What changed, and what is planned.

GET/api/v1/changelogread

Published changelog entries.

GET/api/v1/roadmapread

Planned features and their votes.

POST/api/v1/roadmapwrite

Vote for a feature, or take the vote back.

Body

NameTypeDescription
featureIdrequireduuidThe feature to vote for

Errors and limits

Every failure has the same shape, with the HTTP status to match.

{ "error": "This token is read-only", "code": "forbidden" }
StatusCodeMeaning
400invalid_requestSomething in the request was missing or malformed
401unauthorizedNo token, an unknown one, or an expired one
403forbiddenA read-only token tried to write
404not_foundNo such book, session or bookmark on this account
429rate_limitedToo many requests; wait and retry

Lists are not capped. A request for a shelf returns the whole shelf, and a request for sessions returns every session in the range asked for.