红豆 MCP 使用帮助

红豆 MCP 让外部 AI 助手在你的指令下查找、阅读、导入和整理红豆文献。你可以直接描述任务，例如“查询选中文献的被引次数，并注明来源”，由 AI 调用相应工具完成。

本文按 2026-10-23 的当前客户端校订，覆盖 87 个工具、4 个研究工作流 Prompts，包括引用次数、参考文献格式化、语义证据检索、EndNote 文件导入、专利全文、Obsidian 和独立 LiveSync。你安装的版本可能有所不同，实际能力以设置页的工具数量、客户端工具列表及 hongdou_get_status 为准。

1. 第一次连接

三步开始

1. 打开红豆，进入 设置 → 高级 → MCP 服务，点击 开启连接。如果已显示“已开启”，直接进行下一步。
2. 点击 配置 AI 程序…，找到你使用的程序，点击右侧的 配置。如需选择文件夹，选择你平时在该程序中打开的项目。
3. 完全退出并重启 AI 程序，在新会话中发送下面的连接检查指令。使用期间保持红豆打开。

请调用 hongdou_get_status，告诉我红豆版本、可用工具数量、可访问的资料库，以及是否允许修改文献库。
然后搜索本地文献库中的“机器学习”，返回前 5 条的题名、作者、年份和 itemID。

看到真实的本地文献结果后，再开始阅读或整理任务。没有匹配结果也可能是正常情况，可换用库中已知的题名片段。

连接详情与更多选项 中可以查看当前地址、工具数量、安全设置，并使用 测试连接。测试成功说明红豆端点可以响应；AI 程序仍需加载配置和工具列表。

可以配置哪些 AI 程序

当前内置配置适配覆盖以下 12 款程序：

列表识别主要依据默认位置的配置文件。“已配置”表示红豆已写入或识别配置，不能单独证明程序已安装、当前项目已信任该配置，或该版本已成功加载 MCP。未列出的程序可按其自身说明尝试手动连接，红豆不保证自动适配。

本地连接服务、Local API 和地址

默认地址为：

http://127.0.0.1:18500/mcp

请优先使用设置页显示的实际地址。MCP 需要红豆的本地 HTTP 监听服务；如果提示尚未开启，到本页最下方的“杂项”点击 启用并重启，再开启 AI 助手连接。

“启用 Local API”是另一个设置，并非使用 MCP 的通用前提。 部分 Obsidian 联动功能需要 Local API，应按对应功能的提示配置。

当前版本的 MCP 连接无需 Bearer Token，也不需要手动添加 Authorization 请求头。旧版配置中若保留了红豆认证头，使用“重新配置”，再重启 AI 程序。本文不再沿用旧版的令牌生成、重置流程。

MCP 使用本机 HTTP 地址。只提供云端远程连接的客户端无法直接访问你电脑的 127.0.0.1。手动配置时选择支持的 HTTP MCP 连接方式；红豆通过 POST 处理 MCP 请求，不提供旧式独立 SSE 地址。不同程序配置结构不同，优先使用红豆的配置入口。

2. 直接复制这些提问

不必记住工具名。把资料库、分类和操作范围说清楚，AI 更容易准确执行。

“当前这篇”“选中的文献”应先通过 hongdou_get_ui_focus 定位。它不会改变红豆的选中项。主窗口未打开、标签页不适用或选择超过返回上限时，AI 应说明情况，不能假定已经拿到全部文献。

3. 检索、阅读与引用

本地检索和无关键词浏览

• 按题名、作者等查找已有文献：hongdou_search_items；按标签、引用键或复杂条件查询时使用相应搜索工具。
• 不想输入关键词、只想浏览整个资料库或某个分类：hongdou_list_items。
• 先找分类，再获取成员：hongdou_search_collections → hongdou_get_collection_items。分类重名时按完整位置和 ID 选择，不能直接取第一个。
• 查详情：hongdou_get_item；需要了解文献类型的可用字段时，先查 hongdou_list_item_types 和 hongdou_get_item_type_fields。界面隐藏的空字段不代表数据接口不能读写。

大多数列表不会一次返回全部内容。让 AI 检查返回的分页信息再继续读取；不同工具的分页方式见第 7 节。

查询学术被引次数

hongdou_get_citation_counts 查询已在本地库中的文献，每次 1–20 篇。单篇也使用 itemIDs 数组。

下面的 JSON 展示工具名和参数，交给支持工具调用的 AI 程序使用；所有 ID 均需替换为实际查询结果。

{"name":"hongdou_get_citation_counts","arguments":{"itemIDs":[123,456],"force":false}}

有效观测通常缓存 24 小时，失败有短期冷却。force:true 可请求刷新，仍遵守来源限流；刷新失败不会把旧值冒充成新结果。

不同数据库统计范围不同。不要把多个来源相加，也不要默认把不同来源的次数放进同一个影响力排名。这里查询的是学术被引次数，与文献库中条目之间的“关联”关系不同。

生成参考文献表

先用 hongdou_get_citation_styles 查找本机已安装且支持参考文献表的 CSL 样式，再调用 hongdou_format_bibliography。每次可处理 1–100 篇普通文献，返回 text 或 html。

{"name":"hongdou_get_citation_styles","arguments":{"query":"7714","hasBibliography":true,"limit":20}}

{"name":"hongdou_format_bibliography","arguments":{"itemIDs":[123,456],"locale":"zh-CN","format":"text"}}

省略 styleID 时沿用红豆的默认样式选择；需要特定样式时，传入上一步返回的完整 styleID。显式指定的样式未安装或不支持参考文献表时会报错，不会悄悄换成其他样式。参考文献顺序由 CSL 样式决定。

该工具返回格式化内容，不自动复制到剪贴板，也不修改样式偏好。附件或笔记应先定位到对应的普通文献，再生成参考文献表。

语义检索：给出能回查的证据

关键词不明确、希望按含义查找时，先通过 hongdou_get_semantic_index_status 检查索引，再用 hongdou_search_semantic。

{"name":"hongdou_search_semantic","arguments":{"query":"固态电池界面稳定性的实验研究","mode":"passage","limit":10,"includeText":true}}

• mode:"best-match" 按文献排名；mode:"passage" 查找段落证据。
• 返回原文片段、来源文献、来源类型和 locator，可按资料库、父文献及来源类型缩小范围。
• score 是排名分数，不能解释为结论正确的概率。
• 查询向量可能调用外部 embedding 服务并消耗额度。查询不会自动启用索引；未启用、未就绪、余额不足和正常无命中会分别报告。

需要入队、对账、云端同步、重试、重建或清空索引时，使用 hongdou_manage_semantic_index，先审阅影响再确认。只有 enqueue 接受并要求 itemIDs。管理任务完成只表示该管理命令执行完毕，后台索引和上传进度仍要查询索引状态。

读取 PDF、EPUB、网页与批注

先用 hongdou_get_attachments 获得附件 ID，再读附件。新工作流优先使用 hongdou_get_document_text 获取带真实位置的结构化原文；已有 hongdou_read_pdf 仍可用于 PDF 阅读。

{"name":"hongdou_get_document_text","arguments":{"attachmentID":789,"mode":"structured","maxPages":10}}

PDF 的 pageNumber 从 1 开始，pageIndex 从 0 开始，印刷页标签可能与物理页号不同。EPUB 和网页快照使用 blockRef/position，不生成虚构页码。

每次提取最多返回 128,000 个 UTF-16 单元；有 nextCursor 时继续调用，超大页可能分多次返回。续读使用相同附件和模式，传入实际返回的 cursor，不要同时传 startPage。文件发生变化或游标过期时，从头重新读取。

hongdou_get_pdf_outline 返回实际提取的 PDF 目录及定位信息；某些目录项无法换算成物理页码。目录提取失败与“没有目录”会分别处理。

批注有两个入口：

• 阅读红豆已有批注：hongdou_get_annotations 或 hongdou_search_annotations。
• 把 PDF 文件内嵌批注导入为红豆真实批注：hongdou_import_pdf_annotations，先预览再启动任务，沿用原生去重及定位，结果包含实际新增批注 ID。

只有独立的 PDF/EPUB 附件、尚无父文献时，可用 hongdou_recognize_documents 识别并创建父文献。识别可能联网，返回任务及逐附件结果。

保存阅读笔记与研究报告

先读原文和已有笔记，再让 AI 生成内容。hongdou_create_note 保存新笔记；更新已有笔记前，先读取 hongdou_get_notes 返回的 dateModified/contentHash，在 hongdou_update_note 中带上 expectedDateModified/expectedContentHash，避免覆盖后来修改的内容。

当前没有持久化笔记历史版本查询工具。遇到版本冲突应重新读取并比较，不要反复强行覆盖。

客户端支持 MCP Prompts 时，可选以下工作流；不支持时，直接用自然语言提出相同任务即可。

Prompts 提供任务提示，由外部 AI 助手读取材料、组织分析和输出报告；最终内容仍需核对原文与引用。

4. 导入文献、整理分类和补全信息

DOI、URL、ISBN 和 BibTeX

单篇导入可使用 hongdou_add_by_doi、hongdou_add_by_url 或 hongdou_add_by_isbn。只有想先看元数据、不立即入库时，使用 hongdou_fetch_metadata。网页支持程度取决于可用翻译器及站点访问条件，拿到元数据不一定能下载全文。

hongdou_add_by_bibtex 支持 BibTeX 内容或受限文件；hongdou_export_to_bibtex 可返回字符串，或按文件规则导出。导出到文件需要修改权限及相应确认。

相关说明：网页文献导入。

从 RIS、EndNote 文件批量导入

先把文件及关联附件复制到 红豆数据目录下的 mcp-files 文件夹，不存在时可手动新建。数据目录位置可在高级设置查看，也可通过 hongdou_get_data_directory 查询。

支持 .ris/.enl/.enlx/.enw/.txt/.bib/.bibtex。RIS 相关的 PDF 子目录、EndNote 的 .Data 目录也要一并复制，保持关联结构。导入器会分析实际格式，扩展名并不能保证文件内容有效。

1. 调用 hongdou_analyze_import，先查看格式、文献、附件、笔记、分类数量和警告。
2. 使用返回的 analysisID 调用 hongdou_import_file，指定目标库或分类，以及是否导入附件、笔记和分类。
3. 审阅操作预览并确认，取得 taskId 后继续查询任务，检查逐项结果和所有分页。

{"name":"hongdou_analyze_import","arguments":{"filePath":"/实际红豆数据目录/mcp-files/文献.ris","format":"auto"}}

{"name":"hongdou_import_file","arguments":{"analysisID":"import:实际返回的编号","collectionID":12,"importAttachments":true,"importNotes":true,"importFolders":true,"requestId":"import-review-01"}}

文件在分析、确认或排队期间发生变化时，需要重新分析。结果中的 createdItemIDs 包含实际保存的父文献、子附件和子笔记；还应检查缺失附件、失败记录及分类数量。部分失败时，已经导入的内容会保留，重新导入前先核对实际保存结果。

文件访问范围

给已有文献添加文件可用 hongdou_add_attachment。默认 mode:"copy" 复制附件，不移动原文件；mode:"link" 只支持个人库。路径应来自你明确准备的文件，不要让 AI 猜测。

补全元数据：先看变化再保存

检查这几篇文献缺少哪些字段，生成补全计划，逐篇列出将添加的内容。只预览，等我确认后再应用。

AI 应先调用 hongdou_preview_metadata_update，审阅 changes 和 planID，再通过 hongdou_apply_metadata_update 应用。补全仅针对空字段和缺失作者；计划通常 10 分钟有效，不能由客户端任意改写。文献发生变化后应重新生成计划。

当前预览还会返回 source、sources、channels、requiresReview 和 candidates 等结果。AI 应说明来源状态和需要核对的候选；没有可应用计划、存在身份冲突或要求人工核对时，不应拼造 planID 或直接覆盖题录。账号、权限或文献变化可能使原方案失效。来源需要登录或验证时，先在桌面在线检索对应渠道处理，再生成新预览。

桌面右键 自动更新元数据 已支持单条和批量补空，单条不确定时进入字段确认；MCP 仍按上述“预览 → 审阅 → 应用”流程工作，二者入口不同。详见元数据编辑。

直接编辑使用 hongdou_update_item，字段以类型发现工具的结果为准。传入 creators 会替换完整作者列表，不只是追加一位作者；可带 expectedDateModified 防止覆盖并发修改。

分类、查重和删除

• 添加到分类或移出分类：使用 hongdou_manage_collections。
• 从 A 移动到 B：使用 hongdou_move_items，只移除指定来源分类，保留其他分类关系。sourceCollectionID:null 表示原来未分类。仅支持同库可编辑的顶层条目，可在红豆撤销。
• 查找重复候选：hongdou_find_duplicates。候选相似不等于可以自动合并，应检查类型、标识符、冲突字段及附件。
• 合并：hongdou_merge_duplicates 先预览主条目和迁移内容，再确认执行。使用红豆原生合并，迁移附件、笔记和关系，重复项进入回收站并记录撤销。
• 不是重复项：hongdou_mark_distinct_items 设置 distinct:true；撤销这些条目对的排除关系使用 false，不会清空整库排除记录。
• 删除文献：hongdou_delete_item 默认移入回收站。永久删除另有独立开关和高风险确认，不能按普通删除理解。

5. 在线检索与专利全文

先发现渠道能力，再检索和入库

新工作流建议使用：

查询渠道能力 → 结构化检索 → 查看结果和来源 → 必要时续页或完成原生交互 → 选择结果 → 导入

对应工具为 hongdou_online_search_capabilities → hongdou_online_search_v2 → hongdou_online_search_continue / hongdou_online_search_task → hongdou_import_item。

让 AI 先发现渠道的稳定 ID、可用路由、字段、过滤器、排序和分页能力，再构造 QueryIntent。不同渠道的语法和权限不同，不要假设每个渠道都支持相同条件。hongdou_online_search 保留兼容原有用法。

续页应使用服务返回的 continuation，交给 hongdou_online_search_continue，不要自行拼接令牌。在线检索返回等待任务时，使用专用的 hongdou_online_search_task 查询或取消，不能换用通用 hongdou_get_task。

结果应保留实际来源及 recordId，入库前核对文献身份。缓存记录失效后重新检索，不要猜测或拼造记录。渠道可用、账号登录和全文下载权限是不同状态。

更多渠道用法见 多源在线检索。

官方渠道登录与会话

hongdou_get_provider_status 默认读取本地可用标记；verify:true 才调用渠道适配器校验账号状态，仍不能保证全文权限。

支持原生会话的渠道可用 hongdou_open_provider_session 打开登录或续期窗口。登录、验证码等交互在红豆原生窗口完成，不通过工具参数提交。

{"name":"hongdou_open_provider_session","arguments":{"providerId":"USPTO","action":"login"}}

返回通用 taskId 后用 hongdou_get_task 查询。任务显示交互完成后，还应重新验证渠道状态；关闭窗口本身不代表登录成功。renew/close 的支持情况以渠道能力为准。

明确公开版本，再补取专利文档

USPTO 申请案卷可能包含多个申请公开和授权版本。使用 hongdou_patent_publication 列出版本，再选择返回的明确 versionID；它返回可导入的来源记录，不会直接入库。存在歧义时不要自行选择版本。

为已入库的专利补下载全文，可调用：

{"name":"hongdou_fetch_patent_document","arguments":{"itemID":123,"preferredFormat":"pdf"}}

该工具要求本地文献保存了与当前公开号匹配的来源记录；手工建立但缺少来源记录的专利，可能需要先重新检索并导入明确版本。先审阅预览，再查询下载任务。

preferredFormat 是偏好，最终要看实际结果：原生 PDF、HTML/XML 和生成的阅读副本应分别说明，不能把阅读副本称为官方原始 PDF。需要登录、渠道未提供文档、来源不匹配或条目已改变时会明确报告。

6. 账号、Obsidian 与独立同步

检查账号、权益和服务

工具不接收密码、验证码或登录令牌，也不返回配对密钥。账号切换后，应重新查询能力和状态，旧的任务、确认和计划不能继续使用。

Obsidian 联动

先用 hongdou_get_obsidian_status 查看受管插件版本、登记的 vault、provider 能力及 Local API 标记。paired:null 表示无法确认配对状态，不能解释为已配对或未配对。

hongdou_prepare_obsidian_connection 接受所需 scope 和可选 vaultID，审阅确认后打开原生联动设置。可请求的范围包括 references/materials/noteSync/liveSync，具体以当前 provider 能力为准。

这一工具完成的是设置交接。 用户仍需在红豆中选择 vault、资料库和范围并完成配对；返回的 selectionApplied:false/authorizationGranted:false 表示 MCP 没有自动应用选择或授予访问权限。连接编号也不是配对凭据。

更新受管插件使用 hongdou_update_obsidian_plugin，传入实际 vaultID 和 expectedVersion；尚未安装时版本为空字符串。工具校验内置包，先预览，再启动更新任务。完成后按结果提示重启相关程序。

文献库同步与独立 LiveSync 分开检查

文献库同步使用 hongdou_get_sync_status，显式触发同步使用 hongdou_trigger_sync。

hongdou_get_sync_conflicts 当前明确返回 supported:false，冲突状态未知，不能据此断言“没有冲突”。冲突处理仍在红豆原生同步界面完成。

独立 LiveSync 有另一组接口：

• hongdou_get_livesync_status({refresh:true})：刷新权益、vault 和空间摘要；空间单位为 bytes，未知上限为 null。
• hongdou_list_livesync_devices：分页查询设备，可按 vaultID 筛选。
• hongdou_revoke_livesync_device：核对设备及当前账号归属，预览确认后撤销连接；不删除设备上已有的本地笔记。

文献库同步正常，不能证明独立 LiveSync 同样正常；应分别查看结果。

7. 确认、任务和分页结果

哪些操作会改变数据

“连接详情与更多选项”提供以下开关：

高风险操作包括批量整理、合并、删除、应用补全计划、文件导入、识别、索引管理、受管插件更新和设备撤销等。是否要求确认以该工具返回的预览为准。

预览不是执行结果

首次调用高风险命令通常返回 confirmationRequired:true、具体预览和 confirmationToken，此时尚未执行。

1. 审阅目标、数量、变化及影响。
2. 用相同业务参数和 requestId，附上返回的 confirmationToken 再调用。
3. 默认还需在红豆本地窗口中确认；确认后再检查结果或任务。

令牌通常 120 秒有效，并绑定工具、参数、账号和预览状态。参数或目标内容改变后，应重新预览。确认窗口等待期间，其他读取请求仍可继续响应。

写操作可使用 requestId 防止网络重试重复写入。同一工具、同一 requestId 和相同参数在 10 分钟保留期内重试，会复用原结果；同一编号对应不同参数会被拒绝。一个新的独立操作使用新的编号。它不能替代操作确认，也不是永久去重。

收到 taskId 后继续查询

导入、识别、内嵌批注导入、专利下载、渠道登录、索引管理和插件更新等工作可能返回通用任务。

{"name":"hongdou_get_task","arguments":{"taskId":"task:实际返回的编号","limit":100}}

取消使用：

{"name":"hongdou_cancel_task","arguments":{"taskId":"task:实际返回的编号"}}

取消停止后续工作，正在保存的一条记录可能完成；已保存数据和已消耗额度保留，不自动回滚。partialResult 可以帮助找到实际保存的 ID。

通用任务保存在内存，执行期限通常 15 分钟，终态结果通常保留 30 分钟；最多保留 100 条任务，容量不足时终态结果可能提前清理。停止、重启 MCP 或切换账号会使任务和计划失效。索引任务 completed 只代表管理命令结束，后续后台索引仍需单独检查。

不同工具如何续页

数量和长度限制以各工具 schema 为准。例如被引查询上限 20 篇、参考文献格式化上限 100 篇，不能套用统一批量上限。出现 truncated、警告或剩余页时，AI 应说明尚未读取完整数据。

8. 工具索引（87 个）

以下是当前功能版本的工具名，供核对能力或指定调用。标注“任务”的工具在执行后还需查询结果；具体权限、参数和确认要求以客户端取得的 schema 为准。

连接、环境与字段发现（9）

本地检索与浏览（9）

附件、原文、批注与语义证据（13）

引用、笔记与关联（9）

文献导入与文件（8）

在线检索、渠道与专利（11）

分类、元数据与整理（13）

账号、服务与文献库同步（7）

Obsidian 与独立 LiveSync（6）

通用任务（2）

9. 常见问题

测试连接成功，AI 却看不到工具

确认配置的是正在使用的 AI 程序，以及正确项目或用户范围。完全退出并重启该程序，在新会话中刷新 MCP 工具。检查程序自身是否需要信任项目、启用该服务或允许工具调用。“已配置”与“已加载”是两个步骤。

开启连接失败或地址无法访问

保持红豆运行，检查连接状态和设置页的实际地址。若本地 HTTP 监听被关闭，到“杂项”启用并重启。端口冲突时按红豆提示处理；不要仅靠开启 Local API 判断 MCP 已就绪。

更新后还只有旧工具，或提示需要认证

先确认已经安装包含新功能的红豆版本，并重启红豆。使用“重新配置”更新 AI 程序，完全重启并刷新工具列表。当前版本无需 Bearer Token；旧配置或其他服务的 401 提示不能用来证明红豆当前仍要求令牌。

搜索结果为空，或独立附件读取失败

先确认搜索的是哪个资料库或分类，尝试已知题名片段。不要把普通关键词搜索当作语义检索。独立附件的 ID、父文献 ID 和批注 ID 含义不同，先读取详情确认类型，再交给对应工具。

PDF 没有原文或目录

确认附件已下载、文件存在且未加密。扫描件可能没有可提取文本，当前工具不承诺自动 OCR；目录也可能不存在或无法定位。遇到提取失败应保留错误，不能用 AI 推测的文字或章节冒充原文。

导入提示路径不允许或关联附件缺失

将主文件和关联附件复制到数据目录的 mcp-files 内，保持原有相对目录结构。不要传桌面、下载目录或符号链接路径。核对工具属于新文件导入入口还是仅允许根层 .bib 的旧入口，再重新分析。

任务 completed，但没有全部导入或全文仍在处理

检查逐项 status、错误、缺失附件、partialResult 和结果分页。任务框架完成不等于每条业务记录都成功；索引管理任务结束后还可能有后台索引和云端作业。

取消后已有文献仍然保留

这是任务的预期行为。取消不回滚已经保存的条目，也不退回已经消耗的服务额度。先根据实际保存 ID 核对数据，再决定后续整理或重试范围。

渠道登录成功却不能下载全文

重新校验渠道状态，核对所选公开版本、来源记录和下载权限。登录状态、检索访问权和全文权限不同；渠道也可能只提供 HTML/XML 或阅读副本。以结果中的真实格式和原因说明为准。

账号或服务状态是 unknown/null

这表示当前无法确认，不等于额度为零、未登录或没有设备。按需要显式使用 verify:true 或 refresh:true，再查看返回的验证覆盖范围。登录及机构交互在原生设置中完成。

Obsidian 工具返回连接编号，是否已经完成配对

还需要在红豆原生联动设置中选择范围并完成配对。检查 selectionApplied/authorizationGranted，不要把设置交接完成当作授权成功。独立 LiveSync 和文献库同步也需分别检查。

想让 AI 只查找和阅读

在“连接详情与更多选项”关闭 允许 AI 修改文献库。读取文献仍可能将内容提供给你所用的外部 AI；被引、语义检索和渠道校验也可能联网，语义查询可能消耗额度。

遇到持续故障时，可提供红豆版本、AI 程序版本、工具名、脱敏后的错误和发生步骤。不要在公开反馈中附上密码、验证码、Cookie、密钥或完整私人文献内容。