红豆 MCP 使用帮助

描述红豆 MCP 可以让 Codex、necode、Claude、Cursor 等 AI 助手连接到红豆文献库，并通过自然语言调用红豆提供的文献工具。开启后，用户可以让 AI 帮自己搜索本地文献、查看文献详情、读取 PDF、提取注释、导入文献（支持 DOI/URL/ISBN/BibTeX）、管理分类、查找重复项、批量操作、生成研究报告等完整的文献管理任务。

简单理解：以前 AI 只能根据聊天内容回答问题；连接红豆 MCP 后，AI 可以在你的指令下使用红豆里的 46 个文献管理工具，帮你完成更具体的学术工作。

红豆 MCP 默认通过本机服务工作，地址为：

http://127.0.0.1:18500/mcp

所有 /mcp 请求都需要红豆自动生成的 Bearer Token。普通用户不需要手动输入服务地址或认证令牌，通常只需要在红豆里开启 MCP，并使用“自动适配客户端”即可。

使用前准备

保持红豆处于打开状态

红豆 MCP 是由红豆应用提供的本机服务，因此需要先打开红豆。

红豆打开时，MCP 服务可以使用；
红豆关闭后，MCP 服务会随之不可用；
如果重启了红豆，建议同时重启 AI 客户端，或至少新建一个会话。

如果 AI 客户端提示找不到红豆 MCP，首先检查红豆是否正在运行。

启用本地 API / HTTP 服务

红豆 MCP 依赖红豆的本地 API / HTTP 服务。使用前需要确认该服务已启用。

在红豆设置中找到本地 API / HTTP 服务，并确认它处于开启状态。如果该服务没有开启，AI 客户端就无法连接红豆 MCP。

启用 MCP 服务

在红豆设置中找到 MCP 相关设置，确认 MCP 已启用。

启用后，可以点击“测试连接”。如果测试成功，说明红豆这一端已经准备好。

自动适配 AI 客户端

红豆提供“自动适配客户端”功能，可以把红豆 MCP 地址和认证信息写入常见 AI 客户端的配置文件。

当前红豆会尽量适配以下客户端：

Claude Desktop
Claude Code
Codex
Gemini CLI
Cursor
VS Code
Windsurf
Cline
Roo Code
Continue
Zed
Cherry Studio

如果列表中没有出现某个客户端，通常表示红豆没有在默认位置找到它的配置文件。此时仍然可以按该客户端自己的 MCP 配置方式手动添加红豆 MCP 地址和 Authorization 请求头，具体格式见“高级配置”。

认证与令牌

红豆首次初始化 MCP 服务时会自动生成一个 64 位十六进制认证令牌，并要求客户端通过以下请求头访问 /mcp：

Authorization: Bearer <红豆生成的认证令牌>

推荐使用“自动适配客户端”，红豆会把当前令牌写入客户端配置；
认证令牌相当于本机 MCP 服务的访问凭证，不要粘贴到聊天、截图、日志、工单或公开仓库中；
红豆 MCP 工具不会返回该令牌，读取相关偏好时只会得到 ***REDACTED***；
如果怀疑令牌泄露，可在 MCP 设置中点击“重置认证令牌”；
重置后旧令牌立即失效，必须重新自动适配所有客户端并完全重启这些客户端。

安全设置与默认值

红豆 MCP 设置页提供以下安全开关：

设置	默认值	作用
允许 MCP 修改文献库	开启	关闭后进入只读模式，所有导入、创建、修改、删除、同步触发和文件写入操作都会被拒绝。
允许 MCP 永久删除条目	关闭	即使已经完成高风险确认，默认也只能把条目移入回收站，不能永久删除。
高风险 MCP 操作必须在红豆窗口中确认	开启	AI 提交确认令牌后，用户仍需在红豆本地窗口点击允许；窗口未打开或用户拒绝时不执行。
记录 MCP 写操作审计日志	开启	记录写操作的时间、工具名、耗时、成功状态和脱敏后的参数。

如果只希望 AI 检索和阅读文献，建议关闭“允许 MCP 修改文献库”。不要为了省略确认步骤而长期关闭本地高风险确认。

高风险操作确认流程

以下操作属于高风险操作：修改用户偏好、触发云同步、删除分类、批量调整分类、实际合并重复项、批量更新标签、删除条目，以及把 BibTeX 写入本地文件。重复项的 dryRun=true 预览和只返回 BibTeX 字符串不会触发高风险确认。

高风险操作采用三道保护：

AI 第一次调用时不会执行，红豆只返回操作预览、一次性 confirmationToken 和 120 秒有效期；
AI 必须在有效期内以完全相同的业务参数重新调用，并附上该 confirmationToken；令牌与工具和参数绑定，且只能使用一次；
默认情况下，红豆还会在本地窗口弹出确认框。只有用户点击允许后才会执行；取消、令牌过期、参数变化或红豆主窗口未打开都会拒绝操作。

永久删除还有独立开关。只有“允许 MCP 永久删除条目”已开启，并且上述确认全部通过，permanent=true 才能执行。

本地确认窗口采用非模态方式显示。等待用户确认期间，当前高风险写请求会暂停，但其他搜索、统计和读取类 MCP 请求仍可继续响应。确认窗口超过 120 秒未处理时按拒绝处理。

防止重复写入

所有可能写入数据的工具都支持可选的 requestId。建议 AI 客户端为每个用户意图生成唯一且不超过 128 个字符的请求 ID，并在网络重试时复用它。

10 分钟内，以同一 requestId 和完全相同参数重试，会返回第一次的结果，不会重复创建或修改数据；
两个并发请求使用相同 requestId 和参数时，只会执行一次；
同一 requestId 如果对应不同参数会被拒绝。

requestId 用于防止超时重试造成重复写入，不能代替高风险操作的 confirmationToken 和红豆窗口确认。

文件访问与审计

BibTeX 文件访问采用固定边界：只能读取或写入“红豆数据目录/mcp-files”根层的 .bib 文件。不能访问该目录外的文件，也不能通过子目录或符号链接绕过限制。目录会在首次合法文件操作时自动创建。

启用审计时，每次写操作都会向“红豆数据目录/mcp-audit.jsonl”追加一行 JSON，记录时间、工具名、耗时、是否成功和脱敏参数。认证令牌、正文、BibTeX、注释评论和文件路径等不会写入审计内容。

使用流程

开启红豆 MCP

在红豆中进入设置页面，找到本地 API / HTTP 服务和 MCP 设置。

建议按下面顺序操作：

打开红豆；
进入设置页面；
启用本地 API / HTTP 服务；
启用 MCP 服务；
点击“测试连接”；
测试成功后，再进行客户端适配。

如果测试连接失败，可以先重启红豆，再重新进入设置页面检查服务状态。

适配 Codex

在红豆的“自动适配客户端”页面中找到 Codex，点击适配。

适配成功后，红豆会把类似下面的配置写入 Codex 配置文件：

[mcp_servers.hongdou]
type = "http"
url = "http://127.0.0.1:18500/mcp"
http_headers = { Authorization = "Bearer <由红豆自动写入的认证令牌>" }

用户通常不需要手动编辑这个配置，也不要复制或公开其中的真实令牌。适配完成后，完全退出 Codex 并重新打开。

重启 Codex 后，可以在新会话中输入：

请调用红豆 MCP 工具，在我的红豆本地文献库里检索 Conceptual，返回前 5 条结果，并显示 totalFound、题名、作者、年份、itemID。

如果 Codex 能返回红豆文献库中的真实文献结果，说明 Codex 已经连接到红豆 MCP。

查看 Codex 是否识别到工具

如果不确定 Codex 是否已经识别红豆 MCP，可以直接问：

你现在能看到哪些 MCP 工具？请列出工具名。

正常情况下，工具列表中会出现多个以 hongdou_ 开头的工具，例如 hongdou_search_items、hongdou_get_statistics、hongdou_fetch_metadata 等。

使用 necode 作为备选方案

necode 是一个终端里的编程助手，也支持调用 MCP 服务。如果暂时不能使用 Codex，可以尝试使用 necode。

安装 necode：

npm install -g @aegean-org/necode-cli

进入项目目录并启动：

cd your-project
necode

首次使用时，可以在 necode 中运行：

/login

查看 MCP 状态时，可以运行：

/mcp list

如果 necode 能看到红豆 MCP 工具，就可以使用和 Codex 类似的提问方式：

请调用红豆 MCP 工具，在我的红豆本地文献库里检索 Conceptual，返回前 5 条结果，并显示 totalFound、题名、作者、年份、itemID。

如果 necode 没有自动看到红豆 MCP，可以根据 necode 当前版本的 MCP 配置说明，手动添加红豆 MCP 地址，并设置 Authorization 请求头：

URL: http://127.0.0.1:18500/mcp
Authorization: Bearer <红豆生成的认证令牌>

常用场景

检索本地文献库

当你想查找红豆中已有的文献时，可以让 AI 调用红豆 MCP 搜索本地文献库。

示例：

请调用红豆 MCP 工具，在我的红豆本地文献库里检索 Conceptual，返回前 5 条结果，并显示 totalFound、题名、作者、年份、itemID。

建议让 AI 返回 itemID。后续查看详情、读取附件、创建笔记时，都可以通过 itemID 精确定位文献。

统计文献库和分类

当你想了解当前红豆文献库的整体情况时，可以让 AI 统计文献数量、附件数量和分类结构。

示例：

请调用红豆 MCP 工具，统计我当前红豆文献库的总文献数、附件数、分类数量，并列出顶层分类结构。

这个场景适合在整理文献库、写报告、做文献盘点时使用。

根据 DOI 获取文献元数据

当你知道一篇文献的 DOI，但还没有完整题名、作者、期刊等信息时，可以让 AI 通过 DOI 获取元数据。

示例：

请调用红豆 MCP 工具，用 DOI 10.1038/nature12373 获取文献元数据。请显示题名、作者、期刊、年份、DOI 和数据来源。

如果返回结果正确，可以继续让 AI 把这条文献导入红豆。

查找带 PDF 或附件的文献

如果你想测试 PDF 读取能力，或想找一篇可以继续分析的文献，可以让 AI 先找带附件的条目。

示例：

请调用红豆 MCP 工具，帮我找一篇带 PDF 或附件的文献，并返回 itemID、题名和附件数量。

找到文献后，可以继续查看附件，并读取 PDF。

查看文献详情

当你已经知道某篇文献的 itemID 时，可以查看它的完整信息。

示例：

请查看 itemID 12345 的完整信息，显示题名、作者、年份、DOI、摘要、标签、所在分类、附件数量和笔记数量。

这个操作适合在搜索后继续深入查看某一篇文献。

itemID 也可以是独立附件。此时 hongdou_get_item 会返回附件自身的信息，hongdou_get_attachments 会把该附件作为唯一结果返回，不会因为附件没有父文献而报错。

查看附件并读取 PDF

读取 PDF 前，通常需要先查看文献附件，找到 PDF 对应的 attachmentID。

示例：

请查看 itemID 12345 的附件，找出 PDF 附件，并读取前 5 页。请总结研究问题、研究方法、主要结论和我后续应该重点阅读的部分。

如果 PDF 很长，建议先读取前 5 页或前 10 页，不要一开始就要求读取全文。

生成阅读笔记

红豆 MCP 支持创建和更新笔记。为了避免直接写入不满意的内容，建议先让 AI 生成草稿。

示例：

请根据 itemID 12345 的文献信息和 PDF 前 5 页内容，生成一条阅读笔记草稿。先不要写入红豆，等我确认。

确认后再说：

这条笔记可以写入红豆，请保存到 itemID 12345 下，标签为 精读、方法。

在线检索并导入文献

红豆 MCP 支持在多个在线学术数据库中检索文献，包括 CNKI、万方、arXiv、PubMed、IEEE、Crossref 和 Semantic Scholar。

示例：

请在 Semantic Scholar 搜索 large language model evaluation，返回前 10 条，显示题名、作者、年份、摘要和来源链接。先不要导入，等我选择。

确认要导入后，可以继续说：

请把第 2 条结果导入红豆，添加标签 LLM、待读，并尝试下载 PDF。

检查云同步状态

当你导入了文献、修改了笔记，或怀疑同步异常时，可以让 AI 检查红豆同步状态。

示例：

请检查红豆当前云同步状态，告诉我是否正在同步、上次同步时间、是否有错误或冲突。

如果存在冲突，可以让 AI 列出冲突信息，再回到红豆界面中处理。

工具说明

红豆 MCP 当前由 12 个工具模块提供 46 个工具，覆盖文献搜索、导入、注释、分类管理、数据管理、BibTeX、关联管理等完整的文献管理能力。普通用户不需要背工具名，但了解每个工具的作用，可以帮助你写出更准确的提问。

按代码模块计算：基础搜索与 PDF 7 个、在线搜索与导入 3 个、笔记 3 个、用户与系统 5 个、云同步 3 个、DOI/URL/ISBN 导入 3 个、注释 3 个、分类 5 个、高级搜索 3 个、条目管理 5 个、PDF 目录与条目关联 4 个、BibTeX 2 个，合计 46 个。下文的 4 个 MCP Prompts 是预置研究工作流，不计入工具总数。

2026-08-05 的回归修复覆盖了并发导入事务、独立附件兼容、Unicode 标题重复检测、独立附件 BibTeX 导出提示、数据目录识别、平台信息、同步错误过滤、arXiv 多词查询、精确题名优先排序、Atom 响应 UTF-8 解码和非阻塞本地确认。应用内测试包含 26 项工具回归测试和 13 项缓存/并发测试，均已通过。

2026-08-05 构建后实测记录

重新构建并启动红豆后，已通过真实 MCP 客户端完成以下验证：

MCP 服务成功监听本机 127.0.0.1:18500，鉴权和工具调用正常；
高风险操作第一步只返回预览和短期确认令牌，不会提前修改数据；
第二步会显示红豆本地确认窗口，窗口不会再因初始空白页面的 unload 事件立即拒绝请求；
确认窗口等待期间，另一条带认证的 HTTP 连接调用统计工具约 4 毫秒返回，证明红豆服务端仍可处理读取请求；
用户点击“继续”后，批量标签操作成功处理 2 个测试条目，并通过 hongdou_get_item 读回新增标签；
测试条目随后移入回收站，空测试分类已删除；最终通过 hongdou_search_items 搜索测试题名返回 totalFound=0，没有活动测试数据残留。

arXiv 现场搜索在本次验证时被 export.arxiv.org 以 HTTP 429 限流，直接访问同一上游接口也返回 429，因此未把它记录为红豆功能失败。精确题名优先排序和 Atom UTF-8 解码已由应用内回归测试覆盖；待上游解除限流后可再进行一次真实在线验证。

分页与通用输出限制

常见列表工具采用统一游标分页，包括本地搜索、附件、在线搜索、笔记、同步冲突、注释搜索、分类搜索、分类条目、标签搜索、高级搜索、重复项和关联条目。

limit 默认 20，单页最大 100；
首次调用不传 cursor；
后续调用把上次响应中的 pagination.nextCursor 原样传回；
当前游标格式类似 offset:20，属于服务端值，不建议客户端自行拼接；
分页偏移的安全上限为 10,000；没有下一页时 nextCursor 为 null；
某些数据源无法保证精确总数时，pagination.total 可能为 null。

示例：

{
  "items": [],
  "returned": 20,
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 86,
    "nextCursor": "offset:20"
  }
}

为避免一次调用占用过多内存，写操作中的数组参数最多 50 项，读操作中的数组参数最多 100 项，单个字符串参数最大 2 MB，参数嵌套最多 10 层。需要处理更多数据时，应拆分批次并为每次写操作使用独立 requestId。

1. 基础搜索与浏览

hongdou_search_items：在红豆本地文献库中搜索条目，可按关键词、作者、年份、标签、分类、文献类型等条件检索。
hongdou_get_item：查看某个文献条目的完整信息，包括题名、作者、摘要、DOI、标签、分类、附件和笔记等；支持普通文献和独立附件。
hongdou_get_attachments：列出某篇文献下的所有附件，用于找到 PDF、获取 attachmentID。如果输入的是独立附件 ID，则返回附件自身。
hongdou_get_statistics：统计当前文献库，包括总文献数、附件数、PDF 数、文献类型分布和常用标签等。
hongdou_get_collections：查看红豆分类结构，可列出顶层分类或完整分类树。

2. 高级搜索

hongdou_search_by_tag：按标签搜索文献。支持 AND 逻辑（必须包含所有标签）、OR 逻辑（至少包含一个标签）和排除标签。
hongdou_search_by_citekey：通过 BetterBibTeX 引用键或 Extra 字段中的 Citation Key 搜索文献。
hongdou_advanced_search：高级组合搜索，支持标题、作者、年份范围、DOI、标签、期刊、分类等多字段组合查询。
hongdou_search_annotations：在所有 PDF 注释和评论中搜索关键词。限定的 itemID 可以是普通文献或独立 PDF 附件；非 PDF 独立附件返回空结果。

3. PDF 功能

hongdou_read_pdf：读取 PDF 附件的文字内容，适合总结摘要、引言、方法和结论。默认最多读取 10 页，单次最多 20 页、200,000 个字符；截断时返回 textTruncated 和 originalLength。
hongdou_extract_pdf_metadata：提取 PDF 文件元数据，例如页数、PDF 标题、作者、创建日期、修改日期和本地文件路径。
hongdou_get_pdf_outline：提取 PDF 目录结构（TOC），返回章节标题、层级和页码。

4. PDF 注释管理

hongdou_get_annotations：获取文献的所有 PDF 注释（高亮、评论、下划线等）。支持按附件 ID 或条目 ID 查询，返回页码、位置、颜色等详细信息。
hongdou_create_annotation：在 PDF 附件上创建新的高亮注释，支持多种颜色和添加评论。

5. 文献导入（多种方式）

DOI/URL/ISBN 导入

hongdou_add_by_doi：通过 DOI 自动导入文献，支持批量导入。自动获取元数据，尝试下载开放获取 PDF。
hongdou_add_by_url：通过 URL 导入文献，支持 arXiv、DOI URL、学术网页等。
hongdou_add_by_isbn：通过 ISBN 导入图书。

BibTeX 导入导出

hongdou_add_by_bibtex：通过 BibTeX 字符串或安全目录中的 .bib 文件批量导入文献。文件只能位于“红豆数据目录/mcp-files”根目录，不能读取任意路径或子目录。
hongdou_export_to_bibtex：将文献导出为 BibTeX 格式，优先使用 BetterBibTeX（如已安装）。子附件会自动解析到父文献；没有父文献的独立附件会返回明确错误，不会再返回“成功但内容为空”。可以直接返回字符串；写文件时只能写入“红豆数据目录/mcp-files”根目录，并需要高风险确认。

在线检索导入

hongdou_online_search：在 CNKI、万方、arXiv、PubMed、IEEE、Crossref、Semantic Scholar 等数据库中在线检索文献。arXiv 普通多词关键词默认按短语查询，避免把题名拆成过宽的搜索条件；返回结果会优先排列与查询完全一致的题名，并按 UTF-8 显式解码 Atom 响应，避免摘要中的弯引号等字符乱码。
hongdou_fetch_metadata：通过 DOI、ISBN、PMID、arXiv ID 等标识符获取文献元数据。
hongdou_import_item：把在线检索结果或元数据导入红豆，可选择分类、标签，并尝试下载 PDF。条目和分类关系在同一事务中保存；并发调用由写队列串行化，避免出现“返回失败但条目已经创建”的部分成功。

6. 分类管理

hongdou_create_collection：创建新的文献分类（文件夹），支持创建子分类。
hongdou_delete_collection：删除文献分类（分类中的条目不会被删除）；实际执行需要确认令牌和默认开启的红豆窗口确认。
hongdou_search_collections：按名称搜索分类，支持精确和模糊匹配。
hongdou_manage_collections：批量添加或移除条目到分类中；实际执行需要高风险确认。
hongdou_get_collection_items：获取指定分类中的所有条目，支持递归获取子分类。

7. 数据管理

hongdou_update_item：更新文献元数据，支持更新标题、摘要、日期、标签等所有常见字段。
hongdou_find_duplicates：查找重复条目，支持按标题或 DOI 精确标准化匹配。标题标准化保留中文等 Unicode 文字，不会把多个含 “AI” 的中文题名错误归并成同一组。
hongdou_merge_duplicates：合并重复条目，支持无需写入的 dryRun 预览模式；实际合并需要高风险确认。
hongdou_batch_update_tags：批量添加、移除或替换多个条目的标签；实际执行需要高风险确认。
hongdou_delete_item：删除文献条目。移至回收站需要高风险确认；永久删除默认禁用，需另外开启危险开关。

8. 关联管理

hongdou_get_item_related：获取文献的所有关联条目。
hongdou_add_item_relation：在两个文献之间创建关联关系，支持双向关联。
hongdou_remove_item_relation：删除文献之间的关联关系。

9. 笔记管理

hongdou_get_notes：查看某篇文献的所有笔记，适合检查已有阅读记录。
hongdou_create_note：为某篇文献创建新笔记，支持 Markdown 内容和标签。
hongdou_update_note：修改已有笔记内容，适合补充阅读理解或修订原笔记。

创建和修改笔记前，建议先让 AI 生成草稿，确认后再写入红豆。

10. MCP Prompts（研究工作流）

红豆 MCP 提供 4 个预置研究工作流，通过 MCP Prompts 功能自动搜索文献、提取信息、生成结构化提示词：

literature-review：文献综述生成。自动搜索指定主题的文献，生成综述提示词，默认使用 20 篇、最多 50 篇。
citation-analysis：引用分析。分析特定文献的学术价值、创新点、研究方法等。
research-summary：研究总结。按标签聚合文献，总结领域的主题、成果、方法和发现，最多使用前 50 篇。
export-report：文献报告导出。汇总分类中的前 50 篇文献，包含摘要和 PDF 注释，生成不超过 200,000 个字符的 Markdown 报告。

这些 Prompts 负责组织工具调用和提示词，由当前外部 AI 客户端完成分析与生成，不会调用或向外暴露红豆内置 AI。红豆内置 AI 聊天、文献分析和文献推荐仅供红豆应用内部使用，不属于 MCP 工具。

11. 用户与系统

hongdou_get_user_info：查看当前红豆登录状态，包括用户名、用户 ID、显示名称和账号类型等。
hongdou_get_user_preferences：查看严格允许列表中的偏好设置，例如 MCP 是否启用、调试模式是否开启等；认证令牌始终返回 ***REDACTED***，不在允许列表中的键返回 ***NOT_ALLOWED***。
hongdou_set_user_preference：修改允许修改的偏好设置，普通用户一般较少使用；实际执行需要高风险确认。
hongdou_get_data_directory：查看红豆数据目录信息，包括完整路径、是否存在、顶层文件大小与数量、最后修改时间和数据库路径等。为避免扫描大型文献库，size 和 fileCount 的统计范围由 measurementScope: "topLevel" 明确标识。
hongdou_get_system_info：查看红豆系统信息，例如版本、平台和内存使用情况等。平台从 Mozilla 应用信息中回退识别，User-Agent 使用稳定的 ASCII Hongdou/<version> 格式。

12. 云同步

hongdou_get_sync_status：查看云同步状态，包括用户名、是否正在同步、上次同步时间和错误信息等。错误列表只包含同步运行器维护的错误，不包含普通 JavaScript、插件或 MCP 调试错误。
hongdou_trigger_sync：手动触发云同步，适合导入文献或更新笔记后立即同步；实际触发需要高风险确认。
hongdou_get_sync_conflicts：查看同步冲突列表，帮助判断是否需要回到红豆界面处理冲突。

触发同步属于实际操作，建议在确认需要同步时再执行。

常见问题

AI 客户端看不到红豆 MCP 工具

可以按下面顺序检查：

红豆是否正在运行；
本地 API / HTTP 服务是否已启用；
MCP 服务是否已启用；
红豆设置页中的“测试连接”是否成功；
是否已经在“自动适配客户端”中适配了当前 AI 客户端；
适配后是否完全重启了 AI 客户端；
是否新建了一个会话；
当前 AI 客户端版本是否支持 HTTP 类型 MCP。

也可以在 AI 客户端里问：

你现在能看到哪些 MCP 工具？请列出工具名。

如果列表中出现 hongdou_ 开头的工具，说明红豆 MCP 已经被识别。

测试连接失败

常见原因包括本地 API / HTTP 服务未启用、MCP 未启用、端口被占用、刚修改设置但服务尚未重新启动等。

建议操作：

关闭并重新打开红豆；
重新进入设置页；
确认本地 API / HTTP 服务已启用；
确认 MCP 已启用；
再次点击“测试连接”。

搜索不到文献

可能是关键词太具体、搜索条件过窄，或目标文献不在当前登录用户的文献库里。

可以换一种问法：

请放宽条件，只搜索 Conceptual，不限制年份、作者、分类，返回前 20 条。

也可以先统计文献库：

请统计我的文献库，并列出最近添加的 10 条文献。

PDF 读取失败

常见原因包括没有 PDF 附件、附件路径失效、PDF 文件损坏、PDF 加密，或 PDF 是扫描图片导致无法提取文字。

建议先查看附件：

请查看 itemID 12345 的所有附件，告诉我附件类型、是否存在，以及哪个可以读取。

如果 PDF 是扫描件，可能需要先进行 OCR，再让 AI 读取文本内容。

独立附件能搜索到，但详情或附件读取失败

新版 MCP 已支持把独立附件 ID 传给 hongdou_get_item、hongdou_get_attachments、hongdou_get_annotations 和 hongdou_search_annotations。非 PDF 附件调用 PDF 专用工具时仍会明确返回“该附件不是 PDF 文件”，这是正常的类型校验。

独立附件本身没有标准引文元数据，因此不能直接导出 BibTeX。带父文献的子附件会自动导出父文献；独立附件应先创建或识别父文献，再导出父文献 ID。

高风险确认期间其他 MCP 请求没有响应

新版确认窗口为非模态窗口。等待用户点击允许或取消时，当前写请求保持等待，其他读取请求可以继续执行。如果同一客户端连接中的读取调用仍在排队，可能是客户端自身把 MCP 请求串行化；可使用另一条带认证的 HTTP 连接验证服务端是否可并发响应。如果独立连接也被阻塞，请确认运行的是包含 2026-08-05 回归修复的构建，并重启红豆后重新测试。

arXiv 在线搜索返回 HTTP 429

HTTP 429 表示 arXiv 上游接口正在限流，不等同于红豆 MCP 服务故障。可以稍后重试，避免短时间连续搜索；也可以先使用 Crossref 或 Semantic Scholar 搜索元数据。若红豆已经明确返回上游 429，无需反复重启或重新配置 MCP。

DOI 获取元数据失败

常见原因包括 DOI 输入错误、网络不可用、数据源暂时不可用，或该 DOI 没有公开完整元数据。

可以让 AI 换一种方式搜索：

请检查 DOI 格式是否正确。如果 DOI 查询失败，请尝试用题名在 Crossref 或 Semantic Scholar 搜索。

客户端提示 401 或 Unauthorized

这表示客户端没有携带当前认证令牌，或仍在使用重置前的旧令牌。请回到红豆 MCP 设置，重新执行“自动适配客户端”，然后完全退出并重启客户端。不要在聊天中发送真实令牌来排查问题。

自动适配成功后仍然不能用

很多 AI 客户端只会在启动时读取 MCP 配置。自动适配成功后，需要完全退出并重新打开客户端。

建议按下面顺序处理：

确认红豆仍然打开；
完全退出 AI 客户端；
重新打开 AI 客户端；
新建一个会话；
让 AI 列出当前可见的 MCP 工具。

高级配置

默认地址

红豆 MCP 默认地址为：

http://127.0.0.1:18500/mcp

其中 127.0.0.1 表示本机，18500 是红豆本地 HTTP 服务默认端口，/mcp 是 MCP 端点。只有地址还不够，客户端还必须携带当前 Bearer Token。下面的手动配置只使用占位符；真实令牌应由红豆“自动适配客户端”写入，且不得公开分享。

协议版本与 HTTP 会话

当前服务器协议版本为 2025-11-25，兼容以下 MCP 协议版本：

2024-11-05
2025-03-26
2025-06-18
2025-11-25

客户端可以通过 MCP-Protocol-Version 请求头声明版本。非初始化 HTTP 请求未提供该请求头时，红豆按 2025-03-26 兼容处理；提供不支持的版本会收到 HTTP 400 和错误码 -32005。对象类型的工具结果同时提供 MCP structuredContent，便于新客户端直接读取结构化字段。

红豆当前使用无状态 HTTP 模式：不签发、也不强制要求 Mcp-Session-Id。客户端应通过 POST 发送 JSON-RPC 消息；当前不提供服务器主动 SSE 流。

Codex 手动配置

Codex 配置文件通常位于：

~/.codex/config.toml

可加入：

[mcp_servers.hongdou]
type = "http"
url = "http://127.0.0.1:18500/mcp"
http_headers = { Authorization = "Bearer <红豆生成的认证令牌>" }

保存后，重启 Codex。

通用 JSON 配置

部分客户端使用 JSON 配置，格式可能类似：

{
  "mcpServers": {
    "hongdou": {
      "type": "http",
      "url": "http://127.0.0.1:18500/mcp",
      "headers": {
        "Authorization": "Bearer <红豆生成的认证令牌>"
      }
    }
  }
}

也有客户端使用 serverUrl、httpUrl、http_headers 等字段名。实际字段以对应客户端文档为准。不要把真实令牌提交到版本控制或复制到公开内容中。

Claude Code 项目配置

Claude Code 可使用项目级 .mcp.json。示例：

{
  "mcpServers": {
    "hongdou": {
      "type": "http",
      "url": "http://127.0.0.1:18500/mcp",
      "headers": {
        "Authorization": "Bearer <红豆生成的认证令牌>"
      }
    }
  }
}

把 .mcp.json 放在项目根目录后，在该目录启动 Claude Code 时，就可以加载红豆 MCP。项目级配置可能进入版本控制，必须确认真实令牌不会被提交；优先使用红豆自动适配生成的用户级配置。

重置认证令牌

在红豆 MCP 设置中点击“重置认证令牌”并确认后：

旧令牌立即失效；
已适配客户端会显示为需要重新适配；
对每个需要继续使用的客户端重新执行“自动适配”；
完全退出并重启客户端，再新建会话测试工具列表。

配图建议

如果要把本文发布为图文帮助文档，建议在以下位置插入截图：

“开启红豆 MCP”后插入红豆 MCP 设置页面截图；
“自动适配 AI 客户端”后插入自动适配客户端列表截图；
“适配 Codex”后插入 Codex 适配成功截图；
“检索本地文献库”后插入 AI 调用 hongdou_search_items 的截图；
“统计文献库和分类”后插入 AI 调用统计工具的截图；
“查看附件并读取 PDF”后插入 AI 查找附件或读取 PDF 的截图；
“查看 Codex 是否识别到工具”后插入 MCP 工具列表截图。

小结

红豆 MCP 的核心价值是让 AI 助手从”只能聊天”变成”可以帮你操作红豆文献库”。只要红豆保持打开，MCP 服务已启用，并且 AI 客户端适配成功，就可以在 Codex、necode 或其他支持 MCP 的客户端中，用自然语言完成：

文献搜索（基础搜索、标签搜索、引用键搜索、高级组合搜索）
文献导入（DOI、URL、ISBN、BibTeX、在线检索）
PDF 功能（阅读、注释提取、目录提取、元数据提取）
数据管理（更新元数据、查找重复、合并重复、批量标签操作）
分类管理（创建、删除、搜索、批量管理条目）
关联管理（查看、添加、删除文献关联）
笔记管理（创建、更新、查看）
BibTeX 互操作（导入、导出）
研究工作流（文献综述、引用分析、研究总结、报告生成）
云同步和系统信息查询

当前版本提供 46 个工具和 4 个 MCP Prompts，覆盖学术研究的完整文献管理流程；红豆内置 AI 不通过 MCP 对外提供。

文档更新时间: 2026-08-17 10:36 作者：管理员

红豆MCP使用帮助