libgen-mcp

<p align="center"> <img src="assets/banner.png" alt="libgen-mcp" width="100%"> </p> <p align="center"> [](https://github.com/jmrplens/libgen-mcp/releases/latest) [](LICENSE)  [](https://sonarcloud.io/summary/overall?id=jmrplens_libgen-mcp2) [](https://sonarcloud.io/summary/overall?id=jmrplens_libgen-mcp2) [](https://pkg.go.dev/github.com/jmrplens/libgen-mcp) </p> <p align="center"> [](https://cursor.directory/plugins/libgen-mcp) [](https://glama.ai/mcp/servers/jmrplens/libgen-mcp) [](https://smithery.ai/servers/jmrp/libgen-mcp) [](https://lobehub.com/mcp/jmrplens-libgen-mcp) [](https://libgen-mcp.fly.dev/health) </p> **一个用Go编写的MCP服务器，允许您的AI助手从Library Genesis搜索和下载书籍、研究论文、杂志、漫画和标准。它以一个静态二进制文件（或容器）形式提供，包含三个专注的工具：`search`、`get_details`和`download`。它与Claude、Cursor、VS Code以及任何MCP客户端兼容。** 您可以与AI助手对话，它将执行搜索和获取操作。您不需要跟踪镜像、MD5哈希值或下载网址。镜像会自动发现和缓存，具有透明的故障转移功能，因此即使个别镜像上下线，服务器也能继续工作。 > "为我找到《Clean Code》的最新版本。" · "通过DOI下载那篇论文。" · "搜索漫画《Watchmen》并获取CBR格式。" **📖 完整的文档、安装指南和配置参考 → [jmrplens.github.io/libgen-mcp](https://jmrplens.github.io/libgen-mcp/)** （也支持[Español](https://jmrplens.github.io/libgen-mcp/es/)）。轻量级上下文占用：三个工具为请求添加**~1,900个token**，并且不需要任何账户、API密钥或令牌。同时，它也针对**真实的LLM**进行了验证 - 请参见[评估结果](https://jmrplens.github.io/libgen-mcp/eval-results/)。 --- ## 安装 推荐的安装方式是使用**预编译的静态二进制文件** - 无需Docker、无需Go、无需管理依赖项。从[最新版本](https://github.com/jmrplens/libgen-mcp/releases/latest)下载适用于您平台的资产： ```bash # 示例：Linux amd64（macOS、Windows和arm64构建版本在发布页面上） curl -L -o libgen-mcp \ https://github.com/jmrplens/libgen-mcp/releases/latest/download/libgen-mcp-linux-amd64 chmod +x libgen-mcp && sudo mv libgen-mcp /usr/local/bin/ ``` 二进制文件是完全静态的（`CGO_ENABLED=0`），因此它可以在具有相同操作系统/架构的任何地方运行，而无需安装其他依赖项。每个版本都附带一个`checksums.txt`文件用于验证下载内容。然后，将二进制文件注册到您的MCP客户端 - 请参见下面的[Claude Code](#claude-code-claude-mcp-add)，或参阅[入门指南](docs/getting-started.md)以了解所有客户端。**不需要令牌或账户** - Library Genesis不需要凭证。 ### 更喜欢一键式按钮？（Docker） 以下每个按钮都注册了基于**Docker**的服务器（在首次运行时自动拉取`ghcr.io/jmrplens/libgen-mcp:latest`镜像；您需要安装[Docker](https://www.docker.com/)）。 <table> <tr> <th align="left">客户端</th> <th align="left">一键式按钮</th> </tr> <tr> <td><b>VS Code</b></td> <td><a href="https://insiders.vscode.dev/redirect/mcp/install?name=libgen&amp;config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22ghcr.io%2Fjmrplens%2Flibgen-mcp%3Alatest%22%5D%7D"><img alt="Install in VS Code" src="https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&amp;logo=visualstudiocode&amp;logoColor=white" /></a></td> </tr> <tr> <td><b>VS Code Insiders</b></td> <td><a href="https://insiders.vscode.dev/redirect/mcp/install?name=libgen&amp;config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22ghcr.io%2Fjmrplens%2Flibgen-mcp%3Alatest%22%5D%7D&amp;quality=insiders"><img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/Install_in-VS_Code_Insiders-24bfa5?style=flat-square&amp;logo=visualstudiocode&amp;logoColor=white" /></a></td> </tr> <tr> <td><b>Cursor</b></td> <td><a href="https://cursor.com/install-mcp?name=libgen&amp;config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItaSIsIi0tcm0iLCJnaGNyLmlvL2ptcnBsZW5zL2xpYmdlbi1tY3A6bGF0ZXN0Il19"><img alt="Install in Cursor" src="https://cursor.com/deeplink/mcp-install-dark.svg" height="28" /></a></td> </tr> <tr> <td><b>LM Studio</b></td> <td><a href="https://lmstudio.ai/install-mcp?name=libgen&amp;config=eyJjb21tYW5kIjoiZG9ja2VyIiwiYXJncyI6WyJydW4iLCItaSIsIi0tcm0iLCJnaGNyLmlvL2ptcnBsZW5zL2xpYmdlbi1tY3A6bGF0ZXN0Il19"><img alt="Add to LM Studio" src="https://files.lmstudio.ai/deeplink/mcp-install-dark.svg" height="28" /></a></td> </tr> <tr> <td><b>Kiro</b></td> <td><a href="https://kiro.dev/launch/mcp/add?name=libgen&amp;config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22ghcr.io%2Fjmrplens%2Flibgen-mcp%3Alatest%22%5D%7D"><img alt="Add to Kiro" src="https://kiro.dev/images/add-to-kiro.svg" height="28" /></a></td> </tr> <tr> <td><b>Claude Desktop</b></td> <td><a href="https://github.com/jmrplens/libgen-mcp/releases/latest/download/libgen-mcp.mcpb"><img alt="Download .mcpb extension" src="https://img.shields.io/badge/Download-.mcpb_extension-d97757?style=flat-square&amp;logo=claude&amp;logoColor=white" /></a></td> </tr> </table> **Claude Desktop** 行下载一个本地 [.mcpb桌面扩展](https://github.com/jmrplens/libgen-mcp/releases/latest/download/libgen-mcp.mcpb)（macOS 通用 + Windows，无Docker）- 在Claude Desktop中打开它并确认设置。 ## Claude 代码（`claude mcp add`） 原生二进制文件（首先安装它 - 从[安装](#install) / [最新版本](https://github.com/jmrplens/libgen-mcp/releases/latest)获取预编译二进制文件，或从[源代码](#building)构建）- 然后注册它： ```bash claude mcp add libgen -- /usr/local/bin/libgen-mcp ``` 或Docker（无需安装 - 在首次运行时拉取镜像）： ```bash claude mcp add libgen -- docker run -i --rm ghcr.io/jmrplens/libgen-mcp:latest ``` **然后直接提问：** 打开您的AI客户端，尝试 _"在Library Genesis中搜索Rust书籍。"_ ## 工具 每个结果都通过两个通道返回：结构化的JSON输出（以下字段）和文本内容中的人类可读Markdown渲染。对于`search`，结果表格包含每个结果的可点击下载链接。两个通道都带有`next_steps`指导列表，而搜索指导告诉模型在呈现结果时包含下载链接。 ### `search` 搜索Library Genesis目录。返回包含文件元数据、MD5哈希值和下载选项的分页文件结果，以及分页元数据。 | 参数 | 类型 | 必需 | 描述 | | --- | --- | --- | --- | | `query` | 字符串 | 是 | 搜索文本。 | | `topics` | 字符串数组 | 否 | 搜索的集合：`nonfiction`、`fiction`、`articles`、`magazines`、`comics`、`standards`、`fiction_rus`。省略为所有。 | | `search_in` | 字符串数组 | 否 | 匹配的字段：`title`、`author`、`series`、`year`、`publisher`、`isbn`。省略为所有。 | | `results_per_page` | 整数 | 否 | 每页结果数：`25`、`50`或`100`（默认`25`）。 | | `page` | 整数 | 否 | 结果页，从`1`开始。 | | `order` | 字符串 | 否 | 按以下方式排序：`id`、`time_added`、`title`、`author`、`year`、`size`。 | | `order_mode` | 字符串 | 否 | `asc`或`desc`。 | 响应包括分页元数据，以便模型可以决定是否分页或细化： | 字段 | 类型 | 描述 | | --- | --- | --- | | `next_steps` | 数组 | 模型面对的后续建议，带有现成的示例（例如，使用结果的`md5`/`doi`的`get_details`/`download`调用，或如何扩展无匹配的查询）。每个工具输出都带有此字段。 | | `results` | 数组 | 此页的文件记录。 | | `page` | 整数 | 返回的页码。 | | `results_per_page` | 整数 | 有效的页面大小。 | | `total_files` | 字符串 | 镜像为查询报告的总匹配项。 | | `reachable` | 整数 | 其中有多少个匹配项实际上被解析/可访问。 | | `truncated` | 布尔值 | 当且仅当仅返回匹配项的第一部分时为`true`。 | | `hint` | 字符串 | 当被截断时，建议细化查询（添加作者/年份、仅限标题列、主题）。 | | `has_more` | 布尔值 | 当返回完整页面时为`true`（可能在下一页有更多结果）。 | | `mirror` | 字符串 | 提供查询的镜像。 | ### `get_details` 通过libgen JSON API获取记录的完整元数据（描述、标识符、DOI、封面、相关版本）。通过`md5` **或** `id`查找，不支持两者。 | 参数 | 类型 | 必需 | 描述 | | --- | --- | --- | --- | | `md5` | 字符串 | 两者之一 | 搜索结果中的文件MD5哈希值（返回文件 + 相关版本）。 | | `id` | 字符串 | 两者之一 | 版本或文件ID。 | | `object` | 字符串 | 否 | 使用`id`：`edition`（默认）或`file`。 | ### `download` 将文件下载到本地目录。提供`md5`用于书籍 **或** `doi`用于文章（至少需要一个）；服务器解析适当的源链，对于书籍（`md5`）下载，验证结果与预期哈希值（DOI/文章下载不进行MD5验证）。返回保存的路径、大小和提供它的源。 | 参数 | 类型 | 必需 | 描述 | | --- | --- | --- | --- | | `md5` | 字符串 | 两者之一 | 书籍搜索结果的文件MD5哈希值。 | | `doi` | 字符串 | 两者之一 | 文章搜索结果的DOI；通过DOI获取文章。 | | `path` | 字符串 | 否 | 目标目录（默认：`LIBGEN_MCP_DOWNLOAD_DIR`或`~/Downloads`）。 | | `filename` | 字符串 | 否 | 目标文件名（默认：来自记录元数据或镜像的干净名称）。 | | `source` | 字符串 | 否 | 限制下载到一个源：`libgen`/`randombook`（书籍）或`unpaywall`/`scihub`（文章）。省略以尝试所有并故障转移。 | | `resolve_only` | 布尔值 | 否 | 返回直接下载**URL**作为链接而不是下载。用于远程/托管服务器（它无法写入您的机器）或使用您自己的工具获取文件。默认`false`。 > **文件去向 - 本地 vs. 远程.** 默认情况下，`download`将文件获取到运行**服务器**的机器上。对于带有本地stdio/Docker服务器，这是您自己的机器，因此文件会进入您的下载目录（适用于自主本地代理）。**远程/托管**服务器运行在其他地方，无法写入您的磁盘，因此`download` **始终返回链接** - `resource_link` + 一个`resolved`对象，包含任何必需的`headers` - 您（或您的代理的获取工具）获取该URL，因此文件到达获取的位置。在本地服务器上，您仍然可以传递`resolve_only: true`以选择相同的链接行为每次调用。对于托管**stdio**部署（例如，在Glama上的`mcp-proxy` - [Glama](https://glama.ai/)，其磁盘是短暂的/无法访问的），`LIBGEN_MCP_REMOTE_DOWNLOADS=1`设置为（对于托管**stdio**部署 - 例如，在Glama上的`mcp-proxy`），服务器处于远程模式。 如果同时提供`md5`和`doi`，则优先尝试文章来源，然后尝试书籍来源。 ## 配置 **开箱即用 - 零配置，无需账户.** 以下每个变量都是可选的。常见的设置（将这些作为MCP客户端配置中的`env`条目，或使用Docker时使用`-e NAME=value`）： - **启用开放访问文章（Unpaywall）：** `LIBGEN_MCP_UNPAYWALL_EMAIL=you@example.com` - 默认情况下禁用；Unpaywall API需要一个联系邮箱。没有它，DOI仍然通过Sci-Hub解析。 - **选择文件存放位置：** `LIBGEN_MCP_DOWNLOAD_DIR=/path/to/downloads`（默认`~/Downloads`；`download`工具的`path`参数覆盖每次调用）。 - **固定一个镜像（跳过自动发现）：** `LIBGEN_MIRROR=https://libgen.li`. - **限制来源（例如仅限书籍，无文章来源）：`LIBGEN_MCP_SOURCES=libgen,randombook`. - **下载大小/并发限制：** `LIBGEN_MCP_MAX_DOWNLOAD_BYTES=1073741824`（1 GiB），`LIBGEN_MCP_MAX_CONCURRENT_DOWNLOADS=1`。 完整的参考和调整旋钮（速率限制、重试/停止计划、Sci-Hub主机）都在 **[配置指南](https://jmrplens.github.io/libgen-mcp/configuration/)** 中。 变量 所有变量均为可选；空值或未设置的值将使用默认值。提供的但无效的数值将被视为错误，而不是静默的默认值。 | 变量 | 默认值 | 描述 | | --------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `LIBGEN_MIRROR` | _(自动发现)_ | 强制使用特定镜像，例如 `https://libgen.li`。跳过自动发现。必须是 `http(s)` URL。 | | `LIBGEN_MCP_DOWNLOAD_DIR` | `~/Downloads` | `download` 的默认目标目录（如果不存在则创建，检查可写性）。 | | `LIBGEN_MCP_TIMEOUT` | `30s` | 每个请求的 HTTP 超时时间（Go 时长，例如 `45s`、`1m`）。范围 `(0, 10m]`。 | | `LIBGEN_MCP_LOG_LEVEL` | `info` | 日志级别：`debug`、`info`、`warn` 或 `error`。 | | `LIBGEN_MCP_RATE_RPS` | `1` | 允许的每秒出站请求数。范围 `(0, 20]`。 | | `LIBGEN_MCP_RATE_BURST` | `1` | 最大速率限制突发。范围 `[1, 100]`。 | | `LIBGEN_MCP_MAX_DOWNLOAD_BYTES` | `0` _(无限制)_ | 最大下载大小（字节）。范围 `[0, 50 GiB]`；`0` 禁用上限。 | | `LIBGEN_MCP_MAX_CONCURRENT_DOWNLOADS` | `2` | 允许同时下载的数量。范围 `[1, 16]`。 | | `LIBGEN_MCP_RETRY_ATTEMPTS` | `3` | 在页面请求（搜索/详情/链接解析）时，遍历镜像列表并带有回退；不控制文件下载。范围 `[1, 10]`。 | | `LIBGEN_MCP_DOWNLOAD_START_RETRY_WAITS` | `5s,5s,5s,10s,10s,10s,15s` 下载开始重试之间的阶段等待时间（解析/连接/首字节）。`N` 等待次数 = `N+1` 重试次数（默认约 60 秒）。逗号分隔的 Go 时长；每个在 `(0, 10m]`；最多 20 个。 | | `LIBGEN_MCP_DOWNLOAD_STALL_TIMEOUT` | `60s` | 流式下载时的进度重置停滞窗口：如果在此时间范围内 _没有_ 字节到达，则下载被取消，因此缓慢但进展的传输不会被终止 `(0, 1h]`。 | | `LIBGEN_MCP_UNPAYWALL_EMAIL` | _(未设置 — unpaywall 已禁用)_ | Unpaywall API 的联系邮箱（DOI 查询）。API 拒绝没有邮箱的请求，因此未设置的值会完全禁用 `unpaywall` 源（并将其从下载工具的 `source` 模式中隐藏）。设置您自己的地址以启用它。 | | `LIBGEN_MCP_SCIHUB_HOSTS` | `sci-hub.ee,sci-hub.se,sci-hub.st,sci-hub.ru,sci-hub.wf` | 有序的、逗号分隔的 Sci-Hub 镜像主机（裸主机，无协议）。按顺序尝试直到有一个服务。 | | `LIBGEN_MCP_SOURCES` | _(所有启用)_ | 逗号分隔的下载源白名单：`unpaywall`、`scihub`、`libgen`、`randombook`。 | | `LIBGEN_MCP_REMOTE_DOWNLOADS` | `false` | 强制 `download` 始终返回链接（`resource_link` + `resolved` 对象），而不是保存文件 — 与 `--http` 使用的行为相同。为 **托管 stdio** 部署（例如，通过 `mcp-proxy` 在目录上）设置它，客户端无法访问其磁盘。 `--http` 意味着它；这涵盖了 stdio 托管的情况。接受 `1`/`true`/`0`/`false`。 | ## 多源下载 `download` 运行一个有序的备用链，并在第一个提供有效文件的源处停止： - **书籍（按 `md5`）：** `libgen`（镜像 `ads.php` 密钥 + CDN 重定向）→ `randombook`（新鲜镜像发现）。 - **文章（按 `doi`）：** `unpaywall`（开放访问 PDF，仅当设置了 `LIBGEN_MCP_UNPAYWALL_EMAIL`）→ `scihub`（轮换 Sci-Hub 主机）。 - **`md5` 和 `doi` 都给出：** 首先尝试文章源（`unpaywall`、`scihub`），然后尝试书籍源（`libgen`、`randombook`）。 您可以使用 `LIBGEN_MCP_SOURCES` 限制或重新排序参与的源。附加保证： - **MD5 验证** — 检查书籍下载是否与预期的哈希值匹配，以便拒绝损坏或错误的文件，不保存。 - **可恢复下载** — 中断的传输通过 HTTP 范围请求恢复，而不是重新启动。 - **干净的文件名** — 没有明确的 `filename`，书籍下载命名为 `Author - Title (Year).ext`，从记录元数据中获取，备用为镜像公告的名称。 ## 健壮性 - **镜像故障转移** — 镜像自动缓存和轮换；失败的请求透明地重试下一个活动镜像。 - **重试和回退** — 暂时性 HTTP 故障重试最多 `LIBGEN_MCP_RETRY_ATTEMPTS` 次，并带有指数回退。 - **速率限制** — 出站请求被限制（`LIBGEN_MCP_RATE_RPS` / `LIBGEN_MCP_RATE_BURST`）以保持对镜像的礼貌。 - **温和关闭** — 允许正在进行的任务在终止信号时排空；工具恐慌被恢复，因此 stdio 会话永远不会死亡。 ## 文档 - 指南位于 [`docs/`](docs/)：入门、配置、工具参考、架构和故障排除。 - 完整文档站点（双语 EN/ES）：<https://jmrplens.github.io/libgen-mcp/> ## 构建 使用 Go 安装二进制文件： ```bash go install github.com/jmrplens/libgen-mcp/cmd/server@latest ``` 这会在 `$(go env GOPATH)/bin` 中生成一个名为 `server` 的二进制文件。将它重命名为 `libgen-mcp`（或使用显式名称构建）并将其放在您的 `PATH` 中： go build -o libgen-mcp ./cmd/server ``` 常见的开发者任务由 `Makefile` 封装（`make help` 列出了所有任务）： ```bash make build # 构建服务器二进制文件到 dist/ make test # 运行所有测试并生成覆盖率报告 make lint # golangci-lint + govulncheck make format-md-tables # 规范 Markdown 管 ``` 默认情况下，服务器通过 **stdio** 进行通信。要改为提供 **可流式 HTTP**，请使用 `--http` 和地址（`libgen-mcp --http :8080`）；HTTP 模式还公开了一个 `GET /health` 就绪端点，当服务时返回 `200`。由于 HTTP 服务器是远程的，无法写入客户端的模式下download` 自动返回链接上面的 [本地 vs. 远程](#download)）而不是保存文件。使用 `--version` 显示版本。 ## 维护 Library Genesis 镜像偶尔会更改其 HTML 布局或路由。两个工具可以帮助您检测和确认这些更改： - **实时诊断** — `go run ./cmd/probe` 访问实时镜像并报告每个路由和解析器是否仍然正常工作。如果搜索或下载开始失败，请运行它。 - **选择加入端** — `go test -tags e2e ./test/e2e/` 查询真实站点并断言结果仍然可解析。它被 `e2e` 构建标签所限制，因此在普通的 `go test ./...` 下永远不会运行。 ## 合理使用 此工具访问 Library Genesis 的第三方镜像。您有责任尊重您所在地的版权和知识产权法律。仅合法有权访问的内容使用它。 ## 许可证 参见 [LICENSE](LICENSE)。在 MIT 许可证下发布。