Mendeley Mcp

Mendeley MCP 服务

一个 MCP（Model Context Protocol） 服务，可将你的 Mendeley 参考文献库连接到 Claude Desktop、Cursor 等 LLM 应用，以及其他兼容 MCP 的客户端。

功能

• 搜索你的文献库 - 按标题、作者、摘要或笔记查找论文
• 管理文件夹 - 浏览、创建、重命名、删除和嵌套集合
• 获取完整元数据 - 检索完整的文档详情，包括摘要
• 搜索全球目录 - 访问 Mendeley 收录的 1 亿多篇论文数据库
• DOI 查询 - 根据 DOI 查找论文
• 管理文档 - 在各个文件夹中添加、更新、删除和整理条目
• 读取你的批注 - 查看你在 PDF 上添加的高亮和笔记
• 导出 BibTeX - 为单篇文档或整个文件夹生成引文条目
• 下载附件 - 获取 Mendeley 提供的文档文件

前置条件

1. Mendeley 账户 - 在 mendeley.com 注册（使用 Elsevier 身份验证）
2. Mendeley API 应用 - 在 dev.mendeley.com/myapps.html 注册
   • 使用 Elsevier 凭据登录
   • 点击“Register a new app”
   • 将重定向 URL 设置为 http://localhost:8585/callback
   • 选择“Authorization code”流程（而非 Legacy）
   • 记下你的 Client ID 和 Client Secret

安装

使用 pip

pip install mendeley-mcp

使用 uv（推荐）

uv tool install mendeley-mcp

Intel Mac。 MCP SDK 引入的 cryptography 库从版本 49 起停止发布 macOS x86_64 wheel。在 Intel Mac 上，此软件包将 cryptography 固定在 49 以下，因此无需 Rust 工具链即可安装。该固定版本不再收到上游安全修复；Apple Silicon、Linux 和 Windows 不受影响，并会使用最新版本。

使用 Docker

docker run -it \
  -e MENDELEY_CLIENT_ID="your-client-id" \
  -e MENDELEY_CLIENT_SECRET="your-client-secret" \
  -e MENDELEY_REFRESH_TOKEN="your-refresh-token" \
  ghcr.io/pallaprolus/mendeley-mcp

或者在本地构建：

git clone https://github.com/pallaprolus/mendeley-mcp.git
cd mendeley-mcp
docker build -t mendeley-mcp .

从源代码安装

git clone https://github.com/pallaprolus/mendeley-mcp.git
cd mendeley-mcp
pip install -e .

快速开始

1. 使用 Mendeley 进行身份验证

运行身份验证向导：

mendeley-auth login

此向导将：

1. 提示输入你的 Client ID 和 Client Secret
2. 打开浏览器以授权应用
3. 将凭据安全地保存到系统密钥环

2. 添加到 Claude Desktop

编辑 Claude Desktop 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Linux：~/.config/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mendeley": {
      "command": "mendeley-mcp"
    }
  }
}

如果使用 uv 安装：

{
  "mcpServers": {
    "mendeley": {
      "command": "uvx",
      "args": ["mendeley-mcp"]
    }
  }
}

3. 重启 Claude Desktop

现在应该可以在 Claude 中使用 Mendeley 工具了。

可用工具

工具	描述
mendeley_search_library	搜索知识库中的文档
mendeley_get_document	获取特定文档的完整详情
mendeley_list_documents	列出文档，可按文件夹筛选
mendeley_list_folders	列出所有文件夹／收藏集
mendeley_search_catalog	搜索 Mendeley 的全球论文数据库
mendeley_get_by_doi	通过 DOI 查找论文
mendeley_add_document	向知识库添加新文档
mendeley_update_document	更新现有文档的书目信息、标签或关键词
mendeley_delete_document	永久删除知识库中的文档
mendeley_create_folder	在知识库中创建文件夹，可选择放在父文件夹或群组下
mendeley_rename_folder	重命名现有文件夹
mendeley_delete_folder	删除现有文件夹
mendeley_add_document_to_folder	将现有文档添加到现有文件夹
mendeley_remove_document_from_folder	从文件夹中移除文档，但不删除文档
mendeley_get_annotations	获取文档中 PDF 的高亮和笔记
mendeley_export_bibtex	将文档或文件夹导出为 BibTeX
mendeley_get_file_content	下载知识库或目录文档的第一个附件
mendeley_get_document_text	提取文档附件 PDF 的全文，供模型阅读论文

资源

除了上述工具，服务还会公开两个 MCP 资源。资源不需要参数；支持资源的客户端会将它们与服务一同列出，并允许你将其中一个附加到对话中作为上下文，就像附加文件一样。

资源	内容
mendeley://library/recent	最近修改的 10 篇文档，格式与 mendeley_list_documents 相同
mendeley://library/folders	知识库中的所有文件夹及其 id、name 和 parent_id

工具参考

mendeley_search_library

当论文应该已存在于用户的知识库中时使用此工具。

• 搜索标题、作者、摘要和笔记
• 返回简洁的元数据、格式化的引文文本和 has_pdf
• 在转而搜索目录之前，最好先使用此工具
• 最多返回 limit 条结果（默认值为 20），并按需翻阅 Mendeley 的结果

mendeley_get_document

当你已知知识库中的 document_id 后使用此工具。

• 返回比搜索工具更完整的元数据
• 包含标识符、关键词、标签、时间戳、摘要和 PDF 是否存在
• 适用于检查、总结，以及对已知文档执行后续操作

mendeley_list_documents

使用此工具浏览知识库，而不是按关键词搜索。

• 可将结果限定为特定的 folder_id
• 支持按 last_modified、created 或 title 排序
• 最多返回 limit 篇文档（默认值为 50），并按需翻阅整个知识库；因此，较大的 limit 会返回整个知识库
• 适合查看最近添加的文档或某个收藏集的内容

mendeley_list_folders

在按文件夹列出文档之前，使用此工具了解收藏集层级结构。

• 返回文件夹 ID 和名称
• 包含用于还原嵌套结构的 parent_id
• 当大模型需要安全地浏览知识库结构时，此工具很有用

mendeley_search_catalog

当参考文献不在用户的知识库中，或需要更广泛地查找时，使用此工具。

• 搜索 Mendeley 的全球目录
• 返回 catalog_id、摘要元数据和截断的摘要文本
• 当 mendeley_search_library 未找到匹配项时，可将此工具用作备用方案

mendeley_get_by_doi

当已知 DOI，且希望比自由文本搜索更可靠地查找时，使用此工具。

• 在 Mendeley 目录中解析 DOI
• 返回 catalog_id 和更丰富的目录元数据
• 在使用 mendeley_add_document 或 mendeley_get_file_content 之前，此工具很有用

mendeley_add_document

用于根据已有元数据在文献库中创建条目。

• 创建新的 Mendeley 文献库记录
• 接受标题、作者、年份、来源、摘要和标识符
• 不会单独上传 PDF

mendeley_update_document

用于修正或补充现有文献库条目。

• 仅更新你提供的字段（标题、类型、作者、年份、来源、摘要、标识符、标签、关键词）
• 提供的 tags 或 keywords 列表会替换现有列表；传入 [] 可清空列表。若要添加标签，请先用 mendeley_get_document 读取当前标签，再传入合并后的列表。Mendeley 会将标签存储为集合，并按排序后的顺序返回，而非按传入顺序返回
• 返回更新后的文献状态
• 适用于更正错误年份、补充缺失的摘要、修正标识符，或在文献综述期间为论文添加标签

mendeley_delete_document

用于从文献库中永久删除文献。

• 具有破坏性，且无法通过 API 撤销
• 工具说明会指示模型先向用户确认

mendeley_remove_document_from_folder

用于将文献从文件夹中移出，同时保留在文献库中。

• 与 mendeley_add_document_to_folder 配合使用，可在文件夹之间移动文献
• 不会删除文献本身

mendeley_get_annotations

用于查看用户在论文 PDF 中高亮或添加的备注。

• 返回用户自己的注释：高亮和便笺
• 包含备注文本、高亮颜色和涉及的页码
• 这是了解用户认为论文中哪些内容重要的最直接信号

mendeley_export_bibtex

用于在用户需要规范的参考文献格式时使用。

• 为单条记录提供 document_id，或为整个合集提供 folder_id
• BibTeX 由 Mendeley 本身生成，而非在本地套用模板
• 返回可直接粘贴到 .bib 文件中的原始文本

mendeley_get_file_content

用于尝试下载 Mendeley 为文献库文献或目录检索结果提供的第一个文件。

• 接受文献库 document_id 或 catalog_id
• 返回结构化元数据，并在可用时附带嵌入的 PDF 资源
• 如果不存在文件，会返回明确的无文件结果，而不会静默失败
• 由于版权或许可原因，目录检索结果通常没有可下载的附件
• 大于 10 MB 的文件会报告其大小，但不会嵌入，以免占满客户端的上下文窗口（可通过 MENDELEY_MCP_MAX_FILE_BYTES 环境变量调整）
• 注意：大多数 MCP 客户端（包括 Claude Code）不会将嵌入的 PDF 资源解码为可读内容，而是将其作为原始 base64 传给模型。若要让模型实际阅读论文，请改用 mendeley_get_document_text。

mendeley_get_document_text

用于在用户希望模型阅读、总结论文内容或回答相关问题时使用。

• 接受文献库 document_id 或 catalog_id
• 下载附加的 PDF，并在服务端提取文本，将其作为可读文本块和结构化结果中的 text 字段返回。仅能显示结构化内容的客户端也会收到相同文本（参见 #11）。两种表示形式使用相同的截断上限；为兼容性，响应中会重复包含文本
• 无论采用哪条处理路径，结构化结果都会包含 message，因此仅支持结构化内容的客户端仍可看到文件缺失、扫描版 PDF 和错误的说明
• 仅支持原生数字 PDF；扫描版或仅含图像的 PDF 没有文本层，并会被标记为此类文件（需要进行 OCR）
• 输出上限为 200,000 个字符，结果中会标记是否发生截断（可通过 MENDELEY_MCP_MAX_TEXT_CHARS 环境变量调整）

示例用法

配置完成后，你可以向 Claude 提出如下请求：

• “在我的 Mendeley 文献库中搜索有关 Transformer 架构的论文”
• “我的‘Machine Learning’文件夹里有哪些论文？”
• “查找 DOI 为 10.1038/nature14539 的论文并总结”
• “在 Mendeley 目录中搜索近期有关蛋白质折叠的论文”
• “将这篇论文添加到我的文献库中：[标题、作者等]”
• “在我的 Mendeley 文献库中创建一个名为‘Systematic Review 2026’的文件夹”
• “在文件夹 ID folder-123 下创建一个名为‘Screening’的子文件夹”
• “在群组 group-456 中创建一个名为‘Weekly Reading’的文件夹”
• “将文件夹 folder-123 重命名为‘Included Studies’”
• “从我的 Mendeley 文献库中删除文件夹 folder-999”
• “将文档 doc-789 添加到文件夹 folder-123”
• “将文档 doc-789 从‘Screening’移至‘Included Studies’”
• “修正文档 doc-456 的年份——应该是 2024 年，而不是 2023 年”
• “我在那篇关于注意力机制的论文中标记了什么内容？”
• “将我的‘Lit Review’文件夹导出为 BibTeX”
• “下载那篇关于蛋白质折叠的论文所附的 PDF”

在 MCP 客户端或检查器中直接调用工具时，文件夹管理工具接受如下输入：

创建根文件夹：

{
  "name": "Systematic Review 2026"
}

创建子文件夹：

{
  "name": "Screening",
  "parent_id": "folder-123"
}

重命名文件夹：

{
  "folder_id": "folder-123",
  "name": "Included Studies"
}

删除文件夹：

{
  "folder_id": "folder-999"
}

将文档添加到文件夹：

{
  "folder_id": "folder-123",
  "document_id": "doc-789"
}

感知页码的 PDF 阅读与搜索

mendeley_get_document_text 接受可选的 page_start 和 page_end （页码从 1 开始，且包含边界）。省略边界时，起始页默认选择第一页，结束页默认选择最后一页 PDF 页面。 现有调用仍会返回全文；结构化结果还会包含带边界的 pages 条目，其中包含 page_number、start_offset、end_offset 和 truncated，不会重复包含文本。偏移量是返回的 text 中从零开始计数的 Python 字符位置；结束偏移量不包含在范围内。 偏移量会考虑文本修剪和两个换行符的页面分隔符。若某页面因输出上限而被完全省略，其两个偏移量都指向返回文本的末尾；如果该页面在规范文本中的跨度非空（包括空白字符），则会标记为截断。总文本长度限制同时适用于两种兼容表示形式。页码指 PDF 中的位置， 而不是印刷页码。所选空白页面可能没有可提取的文本。

从 0.7.0 迁移到 0.8.0： pages[].text 已移除。请通过顶层 text 和相应偏移量获取 页面返回的文本：

page_text = result["text"][page["start_offset"]:page["end_offset"]]

JavaScript/TypeScript 字符串索引按 UTF-16 码元计数；这些偏移量按 Unicode 码点计数，每个非 BMP 字符算作一个位置。请使用：

const characters = Array.from(result.text); // Reuse for every page in this result.
const pageText = characters.slice(page.start_offset, page.end_offset).join("");

mendeley_search_document_text(document_id, query, limit=10, context_chars=200) 会在 PDF 的每一页中搜索字面、不区分大小写的短语，包括超出阅读输出上限的页面。它会返回来源元数据、带页码的 片段、字符偏移量、total_matches 和明确的截断标记。 limit 接受 1–100；context_chars 接受 0–2000。搜索会直接使用提取的 文本，因此跨越 PDF 换行符的短语可能无法匹配。返回的 片段始终包含完整匹配项：优先缩减上下文；如果剩余预算不足以容纳短语，则省略该片段。 总匹配数仍会包含被省略的片段。匹配项和片段的偏移量以 原始提取页面文本为索引，而阅读偏移量以返回的文本为索引。 这两种工具在下载和提取出错时都会保留来源元数据。两种 工具都不执行 OCR 或语义搜索。所选空白页面可能没有内容；这并不能证明整个 PDF 都需要 OCR。错误结果包含 document_id、error_stage、file_available 和 text_available； file_available: null 表示尚未确定文件是否可用。输出限制要求文本长度限制为正数，文件限制大于或等于零；设为零会禁用 文件嵌入，同时保留文件元数据。无效配置会在启动时被拒绝。这些 限制不约束 PDF 下载大小或解析工作量。

示例：搜索“evaluation metrics”，然后阅读匹配的 PDF 页面。

文件夹管理验证

• mendeley_create_folder 要求 name 非空。你可以选择提供 parent_id 来创建嵌套文件夹，或提供 group_id 来创建群组范围内的文件夹。
• mendeley_rename_folder 要求 folder_id 和 name 非空。
• mendeley_delete_folder 要求 folder_id 非空。
• mendeley_add_document_to_folder 要求 folder_id 和 document_id 非空。
• 必填字符串输入会在发送请求前去除首尾空白。必填值为空或仅包含空白字符时，会返回 JSON 错误响应，而不会尝试写入。
• 提供可选的 parent_id 和 group_id 值时，会去除其首尾空白，然后直接转发给上游，不执行额外的本地业务规则。
• 重命名和删除操作会将上游返回的文件夹不存在、访问权限或上下文错误作为 JSON 错误响应呈现，而不会返回虚假的成功结果。

mendeley_get_file_content 接受文库文档 ID 或 catalog_id。目录条目通常没有可下载的文件，因此许多情况下预期会返回无文件结果。

配置

环境变量

如果你不想使用 mendeley-auth login，可以通过环境变量配置凭据：

# Required
export MENDELEY_CLIENT_ID="your-client-id"
export MENDELEY_CLIENT_SECRET="your-client-secret"

# One of the following (refresh token recommended - access tokens expire quickly)
export MENDELEY_REFRESH_TOKEN="your-refresh-token"
# OR
export MENDELEY_ACCESS_TOKEN="your-access-token"

可选调优变量：

# Max size of a file embedded by mendeley_get_file_content (default 10 MB)
export MENDELEY_MCP_MAX_FILE_BYTES="10485760"

# Max characters of extracted text returned by mendeley_get_document_text (default 200000)
export MENDELEY_MCP_MAX_TEXT_CHARS="200000"

也可以在 MCP 配置中设置：

{
  "mcpServers": {
    "mendeley": {
      "command": "mendeley-mcp",
      "env": {
        "MENDELEY_CLIENT_ID": "your-client-id",
        "MENDELEY_CLIENT_SECRET": "your-client-secret",
        "MENDELEY_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

身份验证命令

# Check authentication status
mendeley-auth status

# Show environment variables for manual config
mendeley-auth show-env

# Remove saved credentials
mendeley-auth logout

刷新凭据存储

已保存登录的访问令牌过期时，服务会刷新令牌，并将新令牌写回登录凭据的原始存储位置：系统密钥环，或凭据文件。凭据文件会以原子方式替换，并设置私有权限。因此，下次启动服务时即可使用有效令牌，无需再次刷新。

通过环境变量提供的凭据不会写入任何位置；这些部署由用户自行管理令牌的持久性。如果保存失败，当前会话仍会保留刷新的令牌，并在不包含凭据详情的情况下记录警告；下次启动时可能需要再次运行 mendeley-auth login。

开发

设置

git clone https://github.com/pallaprolus/mendeley-mcp.git
cd mendeley-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

测试

# Run tests
pytest

# Run with coverage
pytest --cov=mendeley_mcp

# Type checking
mypy src/mendeley_mcp

# Linting
ruff check src/

使用 MCP Inspector 进行测试

# Install MCP inspector
npm install -g @modelcontextprotocol/inspector

# Run your server with inspector
npx @modelcontextprotocol/inspector mendeley-mcp

架构

┌─────────────────┐     ┌──────────────────┐     ┌───────────────────┐
│  Claude Desktop │────▶│  mendeley-mcp    │────▶│   Mendeley API    │
│  (MCP Client)   │◀────│  (MCP Server)    │◀────│ api.mendeley.com  │
└─────────────────┘     └──────────────────┘     └───────────────────┘
                               │
                               ▼
                        ┌──────────────────┐
                        │  Local Keyring   │
                        │  (credentials)   │
                        └──────────────────┘

重要：此服务在你的本地计算机上运行。你的凭据和数据绝不会经过任何第三方服务——所有通信都直接在你的计算机与 Mendeley API 之间进行。

凭据存储：如果支持密钥环，OAuth 令牌和客户端密钥会存储在系统原生密钥环（macOS Keychain、Windows Credential Locker 或 Linux Secret Service）中，只有客户端 ID 会保存在 ~/.config/mendeley-mcp/credentials.json 中。如果不支持密钥环，凭据会以私有权限保存在该文件中。HTTPX 请求日志会删去签名下载 URL 查询内容，下载错误消息中也不会包含这些内容。

速率限制

Mendeley API 的速率限制按用户计算。如果遇到速率限制：

• 服务会自动刷新令牌
• 等待几分钟后重试
• 如果使用量较大，请考虑将请求分散到一段时间内

故障排除

“未找到凭据”

运行 mendeley-auth login 进行身份验证。

“令牌已过期”

你的访问令牌已过期。服务会使用刷新令牌自动刷新，并将新令牌保存到密钥环或凭据文件中。如果刷新失败，请再次运行 mendeley-auth login。

“401 未授权”

你的应用可能已被取消授权。请使用 mendeley-auth login 重新进行身份验证。

Claude 中未显示服务

1. 检查配置文件路径是否适用于你的操作系统
2. 确保 JSON 格式有效（末尾没有多余的逗号）
3. 完全重启 Claude Desktop
4. 检查 Claude 日志中是否有错误

贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 运行测试和 lint
5. 提交 pull request

许可证

MIT 许可证——请参阅 LICENSE 文件。

免责声明

本项目与 Mendeley 或 Elsevier 无关，也未获得其认可或赞助。Mendeley 是 Elsevier B.V. 的商标。

致谢

• Anthropic 推出的 Model Context Protocol
• MCP Python SDK
• Mendeley API 文档

贡献者

• @roych98 — 报告了 MCP SDK 2.x 安装故障，提供了临时版本固定方案，并编写了 SDK v2 迁移说明（#8）
• @im-alexandre — 文件夹管理工具，改编自 #2
• @Storkholm — 报告并定位了结构化内容的客户端行为（#11）
• @HasiVS — 请求在更新文档时支持标签和关键词（#12），并报告了文件夹列表被截断的问题（#13）