[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_129":130},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":55,"_56":-5,"_57":49,"_58":59,"_60":61,"_62":63,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73,"_74":75,"_76":77,"_78":79,"_80":-5,"_81":-5,"_82":-5,"_83":49,"_84":-5,"_85":86,"_87":88,"_89":90,"_91":92,"_93":94,"_95":96},"apiUrl","https://odel.app/api","creator","cyanheads","moduleId","openlibrary-mcp-server","@cyanheads/openlibrary-mcp-server","displayName","openlibrary mcp server","tagline","Search books and authors, fetch editions, browse subjects, and resolve cover images.","iconKey","https://avatars.githubusercontent.com/u/10339515?v=4","category","remote","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://openlibrary.caseyjhand.com/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1781363414000,"updatedAt",1788329561000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.github.cyanheads%2Fopenlibrary-mcp-server","sourceVerified",true,"sourceMissingSince","importedAt","upstreamStars",3,"upstreamUpdatedAt",1787625370000,"detectedTransport","streamable-http","detectedAuthType","none","probeStatus","ok","lastProbedAt",1787287794000,"githubRepoUrl","https://github.com/cyanheads/openlibrary-mcp-server","githubRepoFullName","cyanheads/openlibrary-mcp-server","releaseId","ext-cyanheads-openlibrary-mcp-server","version","0.2.4","descriptionMarkdown","

@cyanheads/openlibrary-mcp-server

Search books and authors, fetch editions, browse subjects, and resolve cover images from Open Library via MCP. STDIO or Streamable HTTP.\n

10 Tools • 2 Resources

\n\n

\n\n[![Version](https://img.shields.io/badge/Version-0.2.4-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/openlibrary-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/openlibrary-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openlibrary-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.3.0-blueviolet.svg?style=flat-square)](https://bun.sh/)\n\n

\n\n

\n\n[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/openlibrary-mcp-server/releases/latest/download/openlibrary-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=openlibrary-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvb3BlbmxpYnJhcnktbWNwLXNlcnZlciJdfQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22openlibrary-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fopenlibrary-mcp-server%22%5D%7D)\n\n[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n**Public Hosted Server:** [https://openlibrary.caseyjhand.com/mcp](https://openlibrary.caseyjhand.com/mcp)\n\n

\n\n---\n\n## Tools\n\n10 tools for working with Open Library's catalog of 20M+ books, editions, authors, and subjects:\n\n| Tool | Description |\n|:---|:---|\n| `openlibrary_search_books` | Full-text book search with field filters (title, author, subject, publisher, ISBN, language), sort options, pagination, and optional live reading availability |\n| `openlibrary_get_work` | Fetch a work by Open Library Work ID (OL…W) — title, description, subjects, cover IDs, and author IDs |\n| `openlibrary_get_editions` | List editions of a work — publishers, languages, formats, ISBNs, and print run details |\n| `openlibrary_get_edition` | Resolve up to 50 editions in one call by ISBN-10, ISBN-13, OCLC, LCCN, or Open Library Edition ID (OL…M), reporting per-identifier misses |\n| `openlibrary_search_authors` | Search authors by name — returns Author IDs, birth/death dates, top works, and subject associations |\n| `openlibrary_get_author` | Fetch author detail by Open Library Author ID (OL…A) — bio, dates, photo IDs, and linked identifiers from Wikidata, VIAF, ISNI, Goodreads, and LibraryThing |\n| `openlibrary_get_author_works` | List works by an author — titles, cover IDs, and Work OLIDs for drilling into editions or details |\n| `openlibrary_get_subject` | Browse works by subject tag — returns matching works with edition counts and cover IDs plus the total work count |\n| `openlibrary_search_inside` | Full-text search inside the scanned text of Internet Archive books — returns matching items with snippets |\n| `openlibrary_get_cover_url` | Resolve a cover image URL for a book or author photo in S/M/L size — returns a direct HTTPS URL embeddable in markdown |\n\n### `openlibrary_search_books`\n\nFull-text book search across Open Library works.\n\n- Free-text query with Solr field prefixes: `title:`, `author:`, `subject:`, `publisher:`, `isbn:`, `language:`\n- Dedicated filter parameters for title, author, subject, publisher, ISBN, and language\n- Sort by relevance, newest, oldest, community rating, or edition count\n- Pagination via offset for paging through large result sets\n- Optional live reading availability from Internet Archive (borrow/browse/read status) — adds ~200ms latency; off by default\n- Returns work-level records with edition counts, cover IDs, Internet Archive identifiers, and e-book access status\n\n---\n\n### `openlibrary_get_work`\n\nFetch a work by Open Library Work ID (OL…W).\n\n- Title, description, subjects, cover IDs, and linked author IDs\n- Works represent the abstract book concept independent of any specific edition\n- Author names are not included — use `openlibrary_get_author` or `openlibrary_search_books` for names\n\n---\n\n### `openlibrary_get_editions`\n\nList editions of a work — different publishers, languages, formats, and print runs.\n\n- Returns ISBNs, publisher, language, page count, and edition OLIDs\n- Pagination via offset\n- Use after `openlibrary_get_work` or `openlibrary_search_books` to find a specific printing\n\n---\n\n### `openlibrary_get_edition`\n\nResolve one or more editions by identifier.\n\n- Accepts ISBN-10, ISBN-13, OCLC, LCCN, or Open Library Edition ID (OL…M)\n- Takes 1–50 identifiers per call, all of the same `id_type`, resolved in a single upstream request — a bibliography or shelf export costs one call rather than one per book\n- Pass `id_type \"isbn\"` for both ISBN-10 and ISBN-13\n- Returns full edition metadata: authors, publisher, language, all identifier types, and the parent work ID\n- Partial success: identifiers that resolve come back in `editions`, the rest in `unresolved` with a reason (`invalid_identifier` for a value that cannot be the given type, `not_found` for one Open Library holds no record for). The call fails only when nothing resolved\n\n---\n\n### `openlibrary_search_authors`\n\nSearch Open Library authors by name.\n\n- Partial names and alternate names work\n- Returns Open Library Author IDs, names, birth/death dates, top works, and subject associations\n- Use author IDs for `openlibrary_get_author` (bio, remote IDs) or `openlibrary_get_author_works` (list of works)\n\n---\n\n### `openlibrary_get_author`\n\nFetch author detail by Open Library Author ID (OL…A).\n\n- Bio, birth/death dates, photo IDs\n- Linked external identifiers: Wikidata, VIAF, ISNI, Goodreads, and LibraryThing\n- Use `openlibrary_search_authors` to find an author ID first\n\n---\n\n### `openlibrary_get_author_works`\n\nList works by an author.\n\n- Returns titles, cover IDs, and Work OLIDs for drilling into editions or details\n- Use `openlibrary_get_author` for author bio and details, or `openlibrary_get_editions` to explore specific printings\n\n---\n\n### `openlibrary_get_subject`\n\nBrowse works by subject tag.\n\n- Returns matching works with edition counts and cover IDs, plus the total work count for the subject\n- Subjects are user-contributed and may be inconsistent (\"science fiction\", \"Science fiction\", \"SF\" are separate tags)\n- Try lowercase forms first\n\n---\n\n### `openlibrary_search_inside`\n\nFull-text search inside books scanned by the Internet Archive.\n\n- Answers \"which book contains this passage?\" — the one question the metadata tools cannot\n- Quote a phrase for an exact-phrase match; unquoted terms match independently\n- Returns Internet Archive items with the matching passages as snippets and a relevance score\n- Snippets are capped in the text output and complete in `structuredContent`, with the omitted count disclosed\n- Seconds-slow against the live index, an order of magnitude above the metadata endpoints — reach for it deliberately\n- Results key on Internet Archive items, not Open Library works: match the returned `ia_identifier` against the `ia_identifiers` on `openlibrary_search_books` results to reach the catalogue record\n\n---\n\n### `openlibrary_get_cover_url`\n\nResolve a cover image URL for a book or author photo.\n\n- Returns a direct HTTPS URL in the requested size (S/M/L)\n- URLs can be embedded in markdown as `![cover](https://raw.githubusercontent.com/cyanheads/openlibrary-mcp-server/main/url)`\n- The Covers API always returns HTTP 200 — missing covers return a 1×1 placeholder GIF, not a 404, so the identifier format is validated locally first: `id` must be numeric, `isbn` 10 or 13 digits, `olid` an edition OLID (OL…M) for target `book` and an author OLID (OL…A) for target `author`\n\n## Resources\n\n| Type | Name | Description |\n|:---|:---|:---|\n| Resource | `openlibrary://works/{work_id}` | Work detail by Open Library Work ID — title, description, subjects, cover IDs, and author IDs as injectable context |\n| Resource | `openlibrary://authors/{author_id}` | Author detail by Open Library Author ID — name, bio, dates, photo IDs, and linked external identifiers as injectable context |\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):\n\n- Declarative tool definitions — single file per tool, framework handles registration and validation\n- Unified error handling across all tools\n- Pluggable auth (`none`, `jwt`, `oauth`)\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase\n\nOpen Library-specific:\n\n- Complete Open Library REST API integration — Search API, Search Inside (full-text) API, Books API, Authors API, Subjects API, Covers API\n- Configurable `User-Agent` header for well-behaved bot identification per community convention\n- Work → editions → edition drill-down pattern with explicit linking between OLIDs across tools\n- Internet Archive availability lookup (opt-in) for borrow/read status on search results\n\nAgent-friendly output:\n\n- Explicit recovery hints on empty results — echoes search criteria and suggests how to broaden\n- All OLID cross-links surfaced in responses so agents can chain tool calls without re-searching\n- Cover URLs rendered as embeddable markdown image syntax\n\n## Getting started\n\n### Self-Hosted / Local\n\nAdd the following to your MCP client configuration file.\n\n```json\n{\n \"mcpServers\": {\n \"openlibrary-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/openlibrary-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"openlibrary-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/openlibrary-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"openlibrary-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\"run\", \"-i\", \"--rm\", \"-e\", \"MCP_TRANSPORT_TYPE=stdio\", \"ghcr.io/cyanheads/openlibrary-mcp-server:latest\"]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js ≥ 24.0.0).\n- No API key required — Open Library is a free, public API.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/openlibrary-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd openlibrary-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. Key environment variables:\n\n| Variable | Description | Default |\n|:---|:---|:---|\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |\n| `MCP_HTTP_PORT` | HTTP server port | `3010` |\n| `MCP_HTTP_ENDPOINT_PATH` | HTTP endpoint path where the MCP server is mounted | `/mcp` |\n| `MCP_PUBLIC_URL` | Public origin override for TLS-terminating reverse-proxy deployments | none |\n| `MCP_AUTH_MODE` | Authentication: `none`, `jwt`, or `oauth` | `none` |\n| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `warning`, `error`, etc.) | `info` |\n| `MCP_GC_PRESSURE_INTERVAL_MS` | Opt-in Bun-only forced-GC pressure loop (ms). Recommended starting point if heap growth is observed: `60000`. | `0` (disabled) |\n| `LOGS_DIR` | Directory for log files (Node.js only) | `/logs` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1` | `in-memory` |\n| `OPENLIBRARY_USER_AGENT` | User-Agent sent with all Open Library API requests. Include a contact email per community convention. | `openlibrary-mcp-server/1.0 (openlibrary@archive.org)` |\n| `OTEL_ENABLED` | Enable OpenTelemetry | `false` |\n\n## Running the server\n\n### Local development\n\n- **Build and run the production version**:\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:http\n # or\n bun run start:stdio\n ```\n\n- **Run checks and tests**:\n ```sh\n bun run devcheck # Lints, formats, type-checks, and more\n bun run test # Runs the test suite\n ```\n\n## Project structure\n\n| Directory | Purpose |\n|:---|:---|\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Ten tools across Search, Books, Authors, Subjects, and Covers. |\n| `src/mcp-server/resources` | Resource definitions. Work and Author resources. |\n| `src/services/open-library` | Open Library service layer — API client and domain types. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `tests/` | Unit and integration tests, mirroring the `src/` structure. |\n\n## Development guide\n\nSee [`CLAUDE.md`](https://github.com/cyanheads/openlibrary-mcp-server/blob/main/CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for logging, `ctx.state` for storage\n- Register new tools and resources in the `createApp()` arrays\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nThis project is licensed under the Apache 2.0 License. See the [LICENSE](https://github.com/cyanheads/openlibrary-mcp-server/blob/main/LICENSE) file for details.\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_109":110,"_111":112,"_113":114,"_115":116,"_117":118,"_119":120},"requiredSecrets",[],"tags",[99,100,101,102,19,103,104,105,106,107,108],"assets",[],"stats",{"_97":86,"_98":86},"ratingAvg","reviewCount","ai-agent","authors","books","bun","editions","internet-archive","isbn","library","open-library","typescript","topics",[99,100,101,102,19,103,104,105,106,126,127,128,107,108],"license","Apache-2.0","language","TypeScript","registryName","io.github.cyanheads/openlibrary-mcp-server","homepage","https://www.npmjs.com/package/@cyanheads/openlibrary-mcp-server","packages",[121,122],{"_123":124,"_125":22,"_76":77},{"_123":124,"_125":22,"_76":77},"registryType","npm","identifier","mcp","mcp-server","model-context-protocol","ENV",{"_131":132,"_133":134,"_135":136},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]