Docs

MCP server and API

Near Fine’s search is open to assistants and code, free, with no account or API key. One request asks every bookseller serving the buyer’s country and returns their offers together. Through the MCP server, assistants can also set a person’s alerts once the person signs in.

MCP server

URL: https://nearfine.com/mcp
Transport: Streamable HTTP, stateless, with JSON responses
Authentication: None to search. The alert tools sign the person in with OAuth.
Tools: search_books and list_sources, both read-only, and set_alert, list_alerts and cancel_alert

To connect Claude, ChatGPT or Claude Code, follow the steps on AI assistants.

`search_books`

query: Required. An ISBN-10 or ISBN-13, hyphens and spaces allowed, or title and author keywords, with any criteria.
country: The buyer’s country, as an ISO 3166-1 alpha-2 code such as GB. Defaults to US.

Returns the same JSON as the search API, as structured content and as text.

`list_sources`

country: Optional. Lists only the sources serving buyers there.

Returns each source’s name and the countries it serves, or all countries, with any it leaves out under except.

`set_alert`

query: Required, as for search_books, with any criteria the alert should hold out for.
country: Required. The country the book has to reach.

Sets an alert for the signed-in person, or keeps the one already set on that query and country. Returns it as alert, with its id, status and url on Near Fine, and the person’s plan: alerts_allowed, alerts_in_use, how often each is checked and plans_url. A full plan comes back as a tool error.

`list_alerts`

Returns the person’s alerts, finds first, each with id, query, country, status, set_at, checked_at, expires_at, url and, once it has fired, what it found: the listing’s title, seller, condition, price, shipping, total and url, in the person’s currency. Then their plan.

status: pending until its first check notes what’s listed already, which never counts; live while it watches; found once it has emailed a find and stopped; ended when the person got the book; expired after six months; paused when the plan has room for fewer alerts.

`cancel_alert`

id: Required. The alert’s id.

Deletes the alert and returns it as cancelled, with the person’s plan.

Search API

GET https://nearfine.com/api/v3/search?query=9780141439518&country=GB

query: Required, as for search_books.
country: The buyer’s country. Defaults to US.

Expect a few seconds: booksellers are asked live, and a search waits up to eight seconds for them. The response looks like this, with the offers and sources cut short and the links shortened:

{
  "query": "9780141439518",
  "country": "GB",
  "criteria": { "keywords": "9780141439518", "attributes": [] },
  "offers": [
    {
      "title": "Pride and Prejudice",
      "author": "Jane Austen",
      "code": "9780141439518",
      "seller": "World of Books",
      "source": "WorldOfBooks GB",
      "condition": "used",
      "price": 5.4,
      "shipping": 0.0,
      "currency": "GBP",
      "match": 0.73,
      "url": "https://www.awin1.com/…"
    },
    {
      "title": "Pride and Prejudice (Penguin Classics) (Paperback)",
      "code": "173335067129",
      "seller": "eBay",
      "source": "Ebay DE",
      "condition": "very good",
      "price": 3.59,
      "shipping": 2.99,
      "currency": "EUR",
      "buyer_price": 3.01,
      "buyer_shipping": 2.5,
      "buyer_currency": "GBP",
      "match": 0.86,
      "url": "https://www.ebay.de/itm/173335067129?…"
    }
  ],
  "sources": [
    { "name": "Abebooks GB", "offers": 20 },
    { "name": "Ebay GB", "offers": 50 },
    { "name": "Mollat FR", "error": "timed out" }
  ],
  "amazon_url": "https://nearfine.com/out/amazon?country=GB&q=9780141439518",
  "search_url": "https://nearfine.com/search?country=GB&q=9780141439518"
}

criteria: What Near Fine read in the query. See Queries.
offers: Every offer that can reach the buyer, cheapest first. See Offers.
sources: Each source searched, with how many offers it returned, or the error it failed with.
amazon_url: Opens the same search on the buyer’s Amazon site. Amazon doesn’t share its prices with us yet.
search_url: Opens the same search on Near Fine, where a person can also set an alert.

A missing query or an unknown country gets a 400 with an error message.

Queries

An ISBN finds that edition. Title and author keywords find every edition and format. A query can also say what the buyer wants beyond the book, which Near Fine strips from the keywords it sends to booksellers:

Price cap: under $40, below 25 GBP, max 30 € or < 50, in the buyer’s currency when none is named. Offers whose price and known shipping come to more are left out.
Attributes: first edition (also 1st ed., first printing, 1st/1st), signed, dust jacket, hardcover or paperback.
Format: ebook or audiobook, which leaves out offers in other formats.

Words in title case before another capitalised word stay part of the title, as in Hardcover Heaven, and so do words in double quotes. criteria reports what was read:

keywords: What’s left for the booksellers to search.
max_price: The cap, as amount and currency.
attributes: Any of first_edition, signed, dust_jacket, hardcover and paperback.
format: ebook or audiobook, when the query asks for one.
summary: The criteria in words, to show people, as in under £300, first editions, signed.

Offers

title, author: As the bookseller lists them. author is left out where it gives none.
code: The ISBN, or the source’s own id for the listing, such as eBay’s item number.
seller: The bookseller or marketplace.
source: The catalog that found it: the bookseller and the site’s country.
condition: new, used or a grade such as very good, ebook or audiobook.
price, shipping, currency: In the seller’s currency. shipping is left out where the shop doesn’t publish its cost for the buyer’s country. Ebooks and audiobooks never ship, so theirs is 0.
buyer_price, buyer_shipping, buyer_currency: The same in the buyer’s currency, where it differs, at daily exchange rates. Treat them as approximate.
match: From 0 to 1, how sure a decision model is that the listing is the book searched for, in any edition or format, rather than a study guide, summary, adaptation, sequel or another book that shares a word. Below about 0.2 it rarely is. Left out where the listing wasn’t judged.
verdicts: When the query asks for attributes, whether the listing claims each one: true where the decision model confirms it from the listing’s words and any filter the bookseller applied, false where it doesn’t, and left out where unjudged. Ebooks have none of these attributes.
url: Where to buy it.

Offers come cheapest first, counting known shipping. A seller abroad that doesn’t publish shipping sorts as if shipping cost the price again. Some links carry an affiliate tag, which is how Near Fine pays its way, so please pass them on as they are.

Sources

Each source is a bookseller’s site, named with its country, such as Ebay DE. Which ones a search asks depends on the buyer’s country: list_sources lists them, and the about page names them all. Most are searched live. A few come from affiliate feeds, refreshed every six hours.

Alerts

An alert watches a search for six months and emails its owner once, when a new listing turns up with everything the query asks for. Assistants set them with set_alert once the person signs in. The JSON API can’t. On the website, a signed-in person searches and chooses Alert me, so the search_url works too.

The alert tools act for a person, so they need an OAuth 2.1 access token for the MCP server. Searching never does, and nothing asks for one until an alert tool is called. Claude, ChatGPT and Claude Code do all of this themselves.

Challenge: A call to an alert tool without a token, or any call with a token that’s expired or revoked, gets a 401 whose WWW-Authenticate header names resource_metadata and scope="alerts".
Resource: The MCP server’s URL as the assistant was given it, such as https://nearfine.com/mcp, described at /.well-known/oauth-protected-resource/mcp on the same host (RFC 9728). Send it as resource when authorizing and asking for tokens. Tokens work on that server alone.
Authorization server: https://nearfine.com, described at /.well-known/oauth-authorization-server (RFC 8414).
Registration: Dynamic, at /oauth/register (RFC 7591), for public clients. Redirect URIs must be https, or http on localhost, 127.0.0.1 or [::1], which match on any port. Every client is public. One nobody signs in with goes after 90 days.
Authorization: Authorization code with PKCE (S256) at /oauth/authorize. The one scope is alerts. The person signs in with a code we email them, then allows the client. Answers carry iss (RFC 9207).
Tokens: At /oauth/token. Codes last a minute and work once. Access tokens last an hour. Refresh tokens last 90 days and work once: each refresh returns a new one. A retry within a minute gets a fresh pair, and an old one used again after that revokes the connection.
Revocation: At /oauth/revoke (RFC 7009), as disconnecting the assistant from the account page does.

Limits

60 requests a minute per IP across /api and /mcp. Calls to /mcp with an access token count against the person instead, at 120 a minute. Past that, requests get a 429 until the minute is up. Need more? Write to [email protected].

Other endpoints

/api/v2/setup, /api/v2/search: Serve Near Fine’s own search page, one request per source. They change when the page does.
/api/v1/search: A legacy endpoint kept for an existing integration. Build on v3 instead.
/llms.txt: All of this in brief, for agents.