Skip to content
Back to search

mcp-open-library

A Model Context Protocol (MCP) server for the Internet Archive's Open Library API that enables AI assistants to search for book and author information.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/8ensmith--mcp-open-library/badge.svg)](/listings/8ensmith--mcp-open-library)

HTML

<a href="/listings/8ensmith--mcp-open-library"><img src="/api/listings/8ensmith--mcp-open-library/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Quick Start

Nothing to install or build. Point an MCP client at the package with `npx` and it will be fetched on first run:

{
  "mcpServers": {
    "mcp-open-library": {
      "command": "npx",
      "args": ["-y", "mcp-open-library"]
    }
  }
}

In Claude Desktop that goes in `claude_desktop_config.json`; other clients use the same shape. Restart the client and the seven tools below become available.

MCP Registry

This server publishes to the official MCP Registry as `io.github.8enSmith/mcp-open-library` from v1.0.3 onwards. Clients that support the registry can install it by that name.

To inspect the published listing:

curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.8enSmith/mcp-open-library"

Manual Installation

# Clone the repository
git clone https://github.com/8enSmith/mcp-open-library.git
cd mcp-open-library

# Install dependencies
npm install

# Build the project
npm run build

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 516 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # MCP Open Library
  2. [![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0.1%2Fservers%3Fsearch%3Dio.github.8enSmith%2Fmcp-open-library%26version%3Dlatest&query=%24.servers%5B0%5D.server.version&label=MCP%20Registry&prefix=v&color=blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.8enSmith/mcp-open-library)
  3. [![Socket Badge](https://badge.socket.dev/npm/package/mcp-open-library)](https://socket.dev/npm/package/mcp-open-library)
  4. [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/8enSmith/mcp-open-library)](https://archestra.ai/mcp-catalog/8ensmith__mcp-open-library)
  5. [![Listed on MCP ServerList](https://mcp-serverlist.com/api/badge/mcp-open-library)](https://mcp-serverlist.com/mcp/mcp-open-library)
  6. [![NPM](https://nodei.co/npm/mcp-open-library.png?mini=true)](https://npmjs.org/package/mcp-open-library)
  7. A Model Context Protocol (MCP) server for the Open Library API that enables AI assistants to search for book and author information.
  8. <a href="https://glama.ai/mcp/servers/@8enSmith/mcp-open-library">
  9. <img width="380" height="200" src="https://glama.ai/mcp/servers/@8enSmith/mcp-open-library/badge" alt="mcp-open-library MCP server" />
  10. </a>
  11. ## Overview
  12. This project implements an MCP server that provides tools for AI assistants to interact with the [Open Library](https://openlibrary.org/). It allows searching the catalogue by title, author, subject and other fields, searching for authors by name, retrieving detailed author information using their Open Library key, and getting URLs for book covers and author photos. The server returns JSON projections of the Open Library responses rather than the raw payloads.
  13. ## Features
  14. - **Book Search**: Search across titles, authors, subjects, places, people, publishers and ISBNs, with sorting and paging (`search_books`).
  15. - **Book Search by Title**: Search for books using their title (`get_book_by_title`).
  16. - **Author Search by Name**: Search for authors using their name, with paging (`get_authors_by_name`).
  17. - **Get Author Details**: Retrieve detailed information for a specific author using their Open Library key (`get_author_info`).
  18. - **Get Author Photo**: Get the URL for an author's photo using their Open Library ID (OLID) (`get_author_photo`).
  19. - **Get Book Cover**: Get the URL for a book's cover image using various identifiers (ISBN, OCLC, LCCN, OLID, ID) (`get_book_cover`).
  20. - **Get Book by ID**: Retrieve detailed book information using various identifiers (ISBN, LCCN, OCLC, OLID) (`get_book_by_id`).
  21. Search results are paged — every search tool returns at most `limit` results (default 10, maximum 50) alongside `num_found`, the total number of matches, which you page through with `offset` (maximum 1000). The two cover tools check that an image actually exists and say so when it does not, rather than handing back a URL that resolves to a blank placeholder.
  22. Every tool is a read-only lookup and advertises itself as such with the `readOnlyHint` and `openWorldHint` annotations, which may allow a client to skip the confirmation prompt it shows for tools that could change something. These are hints: the MCP specification has clients treat annotations as untrusted unless the server is trusted, so the confirmation policy is the client's to decide. Failures — an unreachable API, a rejected argument — come back as a tool result flagged `isError`, so an assistant can read what went wrong and correct its next call rather than the request failing outright.
  23. ## Installation
  24. ### Quick Start
  25. Nothing to install or build. Point an MCP client at the package with `npx` and it
  26. will be fetched on first run:
  27. ```json
  28. {
  29. "mcpServers": {
  30. "mcp-open-library": {
  31. "command": "npx",
  32. "args": ["-y", "mcp-open-library"]
  33. }
  34. }
  35. }
  36. ```
  37. In Claude Desktop that goes in `claude_desktop_config.json`; other clients use the
  38. same shape. Restart the client and the seven tools below become available.
  39. ### MCP Registry
  40. This server publishes to the official MCP Registry as
  41. `io.github.8enSmith/mcp-open-library` from v1.0.3 onwards. Clients that
  42. support the registry can install it by that name.
  43. To inspect the published listing:
  44. ```bash
  45. curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.8enSmith/mcp-open-library"
  46. ```
  47. ### Manual Installation
  48. ```bash
  49. # Clone the repository
  50. git clone https://github.com/8enSmith/mcp-open-library.git
  51. cd mcp-open-library
  52. # Install dependencies
  53. npm install
  54. # Build the project
  55. npm run build
  56. ```
  57. ## Usage
  58. ### Running the Server
  59. 1. Ensure you are running node v22.23.4 (it'll probably work on a newer version of node but this is what Im using for this test). If you have `nvm` installed run `nvm use`.
  60. 2. In the `mcp-open-library` root directory run `npm run build`
  61. 3. Next run `npm run inspector`. Once built, click the URL with the `MCP_PROXY_AUTH_TOKEN` query string parameter to open the Inspector.
  62. 4. In the Inspector, choose 'STDIO' transport
  63. 5. Make sure the command is set to 'build/index.js'
  64. 6. Click the 'Connect' button in the Inspector - you'll now connect to the server
  65. 7. Click 'Tools' in the top right menu bar
  66. 8. Try running a tool e.g. click get_book_by_title
  67. 9. Search for a book e.g. In the title box enter 'The Hobbit' and then click 'Run Tool'. Server will then return book details.
  68. ### Using with an MCP Client
  69. This server implements the Model Context Protocol, which means it can be used by any MCP-compatible AI assistant or client e.g. [Claude Desktop](https://modelcontextprotocol.io/quickstart/user). The server exposes the following tools:
  70. - `search_books`: Search the catalogue by any combination of query, title, author, subject, place, person, publisher and ISBN
  71. - `get_book_by_title`: Search for book information by title
  72. - `get_authors_by_name`: Search for author information by name
  73. - `get_author_info`: Get detailed information for a specific author using their Open Library Author Key
  74. - `get_author_photo`: Get the URL for an author's photo using their Open Library Author ID (OLID)
  75. - `get_book_cover`: Get the URL for a book's cover image using a specific identifier (ISBN, OCLC, LCCN, OLID, or ID)
  76. - `get_book_by_id`: Get detailed book information using a specific identifier (ISBN, LCCN, OCLC, or OLID)
  77. **Example `search_books` input:**
  78. ```json
  79. {
  80. "author": "Ursula K. Le Guin",
  81. "subject": "fantasy",
  82. "sort": "old",
  83. "limit": 2
  84. }
  85. ```
  86. **Example `search_books` output:**
  87. ```json
  88. {
  89. "num_found": 51,
  90. "offset": 0,
  91. "limit": 2,
  92. "results": [
  93. {
  94. "title": "A Wizard of Earthsea",
  95. "authors": ["Ursula K. Le Guin"],
  96. "first_publish_year": 1968,
  97. "open_library_work_key": "/works/OL59798W",
  98. "edition_count": 87,
  99. "author_keys": ["OL31353A"],
  100. "best_edition": {
  101. "edition_key": "OL5613890M"
  102. },
  103. "cover_url": "https://covers.openlibrary.org/b/id/13617691-M.jpg",
  104. "ratings_average": 3.95,
  105. "ebook_access": "borrowable"
  106. }
  107. ]
  108. }
  109. ```
  110. `best_edition` is one specific edition of the work — the one Open Library ranks best for your query — carrying that edition's own identifiers. Search results otherwise identify a **work** (`open_library_work_key`), which no tool accepts, so this is the route from a search hit to a concrete book.
  111. Its `edition_key` is an OLID you can pass straight to `get_book_by_id` for the full edition record, including its complete ISBN arrays:
  112. ```json
  113. { "idType": "olid", "idValue": "OL5613890M" }
  114. ```
  115. The `isbn_13` / `isbn_10` fields are omitted where Open Library holds no ISBN for that edition — as in the example above, and roughly a third of results — while `edition_key` is essentially always present. Where an edition lists several ISBNs of one kind, the first is reported; `get_book_by_id` returns them all.
  116. The `search_books` tool accepts the following parameters:
  117. - At least one of `q`, `title`, `author`, `subject`, `place`, `person`, `publisher` or `isbn` — the request is rejected without one, since an unfiltered search matches the entire catalogue. `q` takes a free-form Solr query such as `subject:cyberpunk AND first_publish_year:[1980 TO 1990]`
  118. - `language`: Optional 3-letter MARC language code (e.g. `eng`, `fre`)
  119. - `sort`: Optional ordering — `new`, `old`, `random`, `key`, `rating`, `readinglog`, `want_to_read`, `currently_reading`, `already_read` or `title`. Omit for relevance
  120. - `limit`: Optional, 1–50, defaults to 10
  121. - `offset`: Optional, 0–1000, defaults to 0
  122. **Example `get_book_by_title` input:**
  123. ```json
  124. {
  125. "title": "The Hobbit",
  126. "limit": 1
  127. }
  128. ```
  129. **Example `get_book_by_title` output:**
  130. ```json
  131. {
  132. "num_found": 224,
  133. "offset": 0,
  134. "limit": 1,
  135. "results": [
  136. {
  137. "title": "The Hobbit",
  138. "authors": ["J.R.R. Tolkien"],
  139. "first_publish_year": 1937,
  140. "open_library_work_key": "/works/OL27482W",
  141. "edition_count": 481,
  142. "author_keys": ["OL26320A"],
  143. "best_edition": {
  144. "edition_key": "OL51709286M",
  145. "isbn_13": "9780395520215",
  146. "isbn_10": "0395520215"
  147. },
  148. "cover_url": "https://covers.openlibrary.org/b/id/14627509-M.jpg",
  149. "ratings_average": 4.29,
  150. "ebook_access": "borrowable"
  151. }
  152. ]
  153. }
  154. ```
  155. **Example `get_authors_by_name` input:**
  156. ```json
  157. {
  158. "name": "J. R. R. Tolkien",
  159. "limit": 2
  160. }
  161. ```
  162. **Example `get_authors_by_name` output:**
  163. Each result's `key` can be passed to `get_author_info` for that author's full
  164. record. `alternate_names` is abridged here.
  165. ```json
  166. {
  167. "num_found": 2,
  168. "offset": 0,
  169. "limit": 2,
  170. "results": [
  171. {
  172. "key": "OL26320A",
  173. "name": "J.R.R. Tolkien",
  174. "alternate_names": ["John Ronald Reuel Tolkien", "Tolkien"],
  175. "birth_date": "3 January 1892",
  176. "top_work": "The Hobbit",
  177. "work_count": 355
  178. },
  179. {
  180. "key": "OL332676A",
  181. "name": "J. R. R. Tolkien Centenary Conference (1992 Keble College, Oxford)",
  182. "top_work": "Proceedings of the J.R.R. Tolkien Centenary Conference, 1992",
  183. "work_count": 2
  184. }
  185. ]
  186. }
  187. ```
  188. **Example `get_author_info` input:**
  189. ```json
  190. {
  191. "author_key": "OL26320A"
  192. }
  193. ```
  194. **Example `get_author_info` output:**
  195. ```json
  196. {
  197. "name": "J. R. R. Tolkien",
  198. "personal_name": "John Ronald Reuel Tolkien",
  199. "birth_date": "3 January 1892",
  200. "death_date": "2 September 1973",
  201. "bio": "John Ronald Reuel Tolkien (1892-1973) was a major scholar of the English language, specializing in Old and Middle English. He served as the Rawlinson and Bosworth Professor of Anglo-Saxon and later the Merton Professor of English Language and Literature at Oxford University.",
  202. "alternate_names": ["John Ronald Reuel Tolkien"],
  203. "photos": [6791763],
  204. "key": "/authors/OL26320A",
  205. "remote_ids": {
  206. "viaf": "95218067",
  207. "wikidata": "Q892"
  208. },
  209. "revision": 43,
  210. "last_modified": {
  211. "type": "/type/datetime",
  212. "value": "2023-02-12T05:50:22.881"
  213. }
  214. }
  215. ```
  216. **Example `get_author_photo` input:**
  217. ```json
  218. {
  219. "olid": "OL26320A"
  220. }
  221. ```
  222. **Example `get_author_photo` output:**
  223. ```text
  224. https://covers.openlibrary.org/a/olid/OL26320A-L.jpg
  225. ```
  226. When Open Library has no photo for that author, the tool says so instead of returning a URL:
  227. ```text
  228. No author photo available for OLID OL99999999A.
  229. ```
  230. **Example `get_book_cover` input:**
  231. ```json
  232. {
  233. "key": "ISBN",
  234. "value": "9780547928227",
  235. "size": "L"
  236. }
  237. ```
  238. **Example `get_book_cover` output:**
  239. ```text
  240. https://covers.openlibrary.org/b/isbn/9780547928227-L.jpg
  241. ```
  242. As with author photos, a book with no cover produces a message rather than a URL:
  243. ```text
  244. No cover image available for OLID OL00000000M.
  245. ```
  246. The `get_book_cover` tool accepts the following parameters:
  247. - `key`: The type of identifier (one of: `ISBN`, `OCLC`, `LCCN`, `OLID`, or `ID`)
  248. - `value`: The value of the identifier
  249. - `size`: Optional cover size (`S` for small, `M` for medium, `L` for large, defaults to `L`)
  250. **Example `get_book_by_id` input:**
  251. ```json
  252. {
  253. "idType": "isbn",
  254. "idValue": "9780547928227"
  255. }
  256. ```
  257. **Example `get_book_by_id` output:**
  258. ```json
  259. {
  260. "title": "The Hobbit",
  261. "authors": [
  262. "J. R. R. Tolkien"
  263. ],
  264. "publishers": [
  265. "Houghton Mifflin Harcourt"
  266. ],
  267. "publish_date": "October 21, 2012",
  268. "number_of_pages": 300,
  269. "isbn_13": [
  270. "9780547928227"
  271. ],
  272. "isbn_10": [
  273. "054792822X"
  274. ],
  275. "oclc": [
  276. "794607877"
  277. ],
  278. "olid": [
  279. "OL25380781M"
  280. ],
  281. "open_library_edition_key": "/books/OL25380781M",
  282. "open_library_work_key": "/works/OL45883W",
  283. "cover_url": "https://covers.openlibrary.org/b/id/8231496-M.jpg",
  284. "info_url": "https://openlibrary.org/books/OL25380781M/The_Hobbit",
  285. "preview_url": "https://archive.org/details/hobbit00tolkien"
  286. }
  287. ```
  288. The `get_book_by_id` tool accepts the following parameters:
  289. - `idType`: The type of identifier (one of: `isbn`, `lccn`, `oclc`, `olid`)
  290. - `idValue`: The value of the identifier
  291. An example of this tool being used in Claude Desktop can be see here:
  292. <img width="1132" alt="image" src="https://github.com/user-attachments/assets/0865904a-f984-4f7b-a27d-6397ac59d6d2" />
  293. ### Docker
  294. You can test this MCP server using Docker. To do this first run:
  295. ```bash
  296. docker build -t mcp-open-library .
  297. docker run -p 8080:8080 mcp-open-library
  298. ```
  299. You can then test the server running within Docker via the inspector e.g.
  300. ```bash
  301. npm run inspector http://localhost:8080
  302. ```
  303. ## Development
  304. ### Project Structure
  305. - `src/index.ts` - The MCP server: builds the HTTP clients and drives both request handlers
  306. from the tool registry
  307. - `src/index.test.ts` - Tests for the server wiring, including a snapshot of the published
  308. tool schemas
  309. - `src/tools/<tool-name>/` - One directory per tool, each containing `index.ts` (the
  310. handler, its Zod argument schema and its `ToolDefinition`), `index.test.ts`, and — for
  311. tools with a non-trivial API response — a `types.ts` describing that response shape
  312. - `src/tools/registry.ts` - The `TOOLS` array, the single list of what the server exposes
  313. - `src/tools/types.ts` - The `ToolDefinition` and `ToolHandler` contracts
  314. - `src/utils/` - Shared plumbing: `http.ts` (the API and covers Axios clients), `errors.ts`
  315. (argument parsing and error results), `results.ts`, `schema.ts` (Zod → JSON Schema),
  316. `search.ts` (the shared search projection and paging schemas), `covers.ts`
  317. - `scripts/` - Release automation (`sync-server-json.mjs`, `promote-changelog.mjs`,
  318. `assert-release-consistency.mjs`) and its tests
  319. A tool's input contract is declared once, as a Zod schema. The JSON Schema that MCP clients
  320. see is generated from it by `toInputSchema`, so the two cannot drift. Field descriptions come
  321. from `.describe()` on the Zod schema. Note that `.refine()` constraints are dropped in
  322. translation — a cross-field rule has to be stated in the tool's `description` too, or clients
  323. will never learn about it.
  324. Adding a tool means creating the directory and adding one entry to `TOOLS` in
  325. `src/tools/registry.ts`. `src/index.test.ts` derives its expectations from that array, so the
  326. only test change is an updated schema snapshot (`npx vitest run -u`).
  327. ### Available Scripts
  328. - `npm run build` - Build the TypeScript code
  329. - `npm run watch` - Watch for changes and rebuild
  330. - `npm test` - Run the test suite in watch mode
  331. - `npm run test:precommit` - Run the test suite once and exit
  332. - `npm run lint` / `npm run lint:fix` - Lint `src` and `scripts` with ESLint
  333. - `npm run format` - Format code with Prettier
  334. - `npm run inspector` - Run the MCP Inspector against the server
  335. ### Running Tests
  336. `npm test` starts Vitest in watch mode:
  337. ```bash
  338. npm test
  339. ```
  340. For a single pass — what the pre-commit hook and CI run — use:
  341. ```bash
  342. npm run test:precommit
  343. ```
  344. To run one file or one test case:
  345. ```bash
  346. npx vitest run src/tools/get-book-by-id/index.test.ts
  347. npx vitest run -t "should return book details when given a valid OLID"
  348. ```
  349. ### Releasing
  350. Releases are automated. Pushing a `v*` tag triggers
  351. [`publish-mcp.yml`](.github/workflows/publish-mcp.yml), which runs the checks, publishes the package
  352. to npm, registers the new version with the MCP Registry, and then creates a GitHub Release using
  353. that version's `CHANGELOG.md` section as the notes. Both npm and the registry authenticate over
  354. GitHub OIDC, so there are no publishing secrets to manage.
  355. `package.json`'s `version` is the single source of truth. `npm version` derives everything else from
  356. it via a `version` lifecycle hook, so a release is one command:
  357. ```bash
  358. npm version patch # or minor / major
  359. git push --follow-tags
  360. ```
  361. That single command bumps `package.json`, rewrites `server.json` to match, promotes the changelog's
  362. `## [Unreleased]` heading to the new version and today's date, and commits the lot under one tag.
  363. Two things to know before you run it:
  364. - **Write your changelog entries first.** They go under a `## [Unreleased]` heading in
  365. [`CHANGELOG.md`](CHANGELOG.md) as you merge work. `npm version` fails if that heading is missing,
  366. rather than releasing something undocumented. If it does fail, undo the partial bump with
  367. `git restore --source=HEAD --staged --worktree package.json package-lock.json server.json`.
  368. - **The working tree must be clean**, and the pre-commit hook (lint + full test suite) runs inside
  369. `npm version`.
  370. CI re-asserts that the tag, `package.json`, `server.json` and `CHANGELOG.md` all agree before
  371. anything is published — see `scripts/assert-release-consistency.mjs`. The same check runs on pull
  372. requests that touch those files.
  373. #### `npm version` is not a retry
  374. Once it prints the new tag, the commit and tag exist and the release is done locally — the next step is
  375. `git push --follow-tags`, **not** running `npm version` again. A second run attempts the *next*
  376. version, and will fail on the missing `## [Unreleased]` heading (which the first run consumed). That
  377. failure is safe by design, but it leaves `package.json`, `package-lock.json` and `server.json`
  378. bumped and uncommitted. Undo with:
  379. ```bash
  380. git restore --source=HEAD --staged --worktree package.json package-lock.json server.json
  381. ```
  382. #### If the publish workflow fails
  383. Re-running the job from the Actions tab only helps for a transient failure. GitHub runs the workflow
  384. **as it existed at the tagged commit**, so a bug in the workflow itself or in `server.json` cannot be
  385. fixed by a re-run — the fix has to be in the commit the tag points at.
  386. Nothing is published until the workflow reaches its npm step, so if it failed before then, the
  387. version is still free and you can move the tag:
  388. ```bash
  389. # fix the problem on main and commit it first
  390. VERSION="$(node -p "require('./package.json').version")"
  391. git push origin ":v${VERSION}" # delete the remote tag e.g. git push origin :v1.0.3
  392. git tag -d "v${VERSION}" # delete it locally
  393. git tag -a "v${VERSION}" -m "${VERSION}" # re-tag at the fixed commit
  394. git push origin "v${VERSION}"
  395. ```
  396. The fix commit must leave `package.json` on that same version, or the consistency check will reject
  397. the tag. If npm *did* already publish, do not reuse the version — that release is immutable. Bump to
  398. the next patch instead; the guarded npm step means a re-run skips what already succeeded.
  399. ## Contributing
  400. Contributions are welcome! Please feel free to submit a pull request.
  401. ## Acknowledgments
  402. - [Open Library API](https://openlibrary.org/developers/api)
  403. - [Model Context Protocol](https://github.com/modelcontextprotocol)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.