\n\n[](https://github.com/cyanheads/openlibrary-mcp-server/releases/latest/download/openlibrary-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=openlibrary-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvb3BlbmxpYnJhcnktbWNwLXNlcnZlciJdfQ==) [](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[](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 ``\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`](./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](./LICENSE) file for details.\n",
"bytes": 14423,
"sha": "12125eb95ce22221ef4f0acd761a05de8d47a155d2e72043b3cc55b751679dc0",
"repo_slug": "cyanheads/openlibrary-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_openlibrary_mcp_serv_f99858b7/readme"
}