红豆 MCP 使用帮助

描述红豆 MCP 可以让 Codex、necode、Claude、Cursor 等 AI 助手连接到红豆文献库，并通过自然语言调用红豆提供的文献工具。开启后，用户可以让 AI 帮自己搜索本地文献、查看文献详情、读取 PDF、生成阅读笔记、在线检索文献、导入文献和检查同步状态。

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

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

http://127.0.0.1:23119/mcp

普通用户不需要手动输入这个地址。通常只需要在红豆里开启 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 地址。

使用流程

开启红豆 MCP

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

建议按下面顺序操作：

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

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

适配 Codex

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

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

[mcp_servers.hongdou]
type = "http"
url = "http://127.0.0.1:23119/mcp"

用户通常不需要手动编辑这个配置。适配完成后，完全退出 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 地址：

http://127.0.0.1:23119/mcp

常用场景

检索本地文献库

当你想查找红豆中已有的文献时，可以让 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、摘要、标签、所在分类、附件数量和笔记数量。

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

查看附件并读取 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 当前提供 6 大类、24 个工具。普通用户不需要背工具名，但了解每个工具的作用，可以帮助你写出更准确的提问。

文献库搜索与浏览

hongdou_search_items：在红豆本地文献库中搜索条目，可按关键词、作者、年份、标签、分类、文献类型等条件检索。
hongdou_get_item：查看某个文献条目的完整信息，包括题名、作者、摘要、DOI、标签、分类、附件和笔记等。
hongdou_get_attachments：列出某篇文献下的所有附件，用于找到 PDF、获取 attachmentID。
hongdou_read_pdf：读取 PDF 附件的文字内容，适合总结摘要、引言、方法和结论。
hongdou_extract_pdf_metadata：提取 PDF 文件元数据，例如页数、PDF 标题、作者、创建日期和修改日期。
hongdou_get_statistics：统计当前文献库，包括总文献数、附件数、PDF 数、文献类型分布和常用标签等。
hongdou_get_collections：查看红豆分类结构，可列出顶层分类或完整分类树。

AI 辅助研究

hongdou_ai_chat：调用红豆 AI 进行问答，可结合指定文献或附件进行解释和讨论。
hongdou_analyze_literature：对一篇或多篇文献进行结构化分析，支持总结、方法分析、发现提取、文献对比和趋势分析。
hongdou_recommend_items：根据已有文献或标签推荐相关研究，适合扩展阅读列表或准备综述。

如果红豆 AI 没有配置好，这一类工具可能会提示不可用。此时需要先检查红豆中的 AI 设置。

在线检索与导入

hongdou_online_search：在 CNKI、万方、arXiv、PubMed、IEEE、Crossref、Semantic Scholar 等数据库中在线检索文献。
hongdou_fetch_metadata：通过 DOI、ISBN、PMID、arXiv ID 等标识符获取文献元数据。
hongdou_import_item：把在线检索结果或元数据导入红豆，可选择分类、标签，并尝试下载 PDF。

导入文献会改变红豆数据，建议先让 AI 展示准备导入的文献信息，确认后再导入。

笔记管理

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

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

用户与系统信息

hongdou_get_user_info：查看当前红豆登录用户信息，例如用户名、用户 ID、账号类型等。
hongdou_get_user_preferences：查看用户偏好设置，例如 MCP 是否启用、调试模式是否开启等。
hongdou_set_user_preference：修改允许修改的偏好设置，普通用户一般较少使用。
hongdou_get_data_directory：查看红豆数据目录信息，包括路径、目录大小和文件数量等。
hongdou_get_system_info：查看红豆系统信息，例如版本、平台和内存使用情况等。

这一类工具常用于确认当前登录账号、排查问题或给技术支持提供信息。

云同步

hongdou_get_sync_status：查看云同步状态，包括是否正在同步、上次同步时间和错误信息等。
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 读取文本内容。

DOI 获取元数据失败

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

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

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

AI 分析工具不可用

红豆 AI 辅助研究工具依赖红豆内置 AI 功能。如果红豆 AI 没有配置好，相关工具可能会提示不可用。

可以先检查红豆 AI 设置，也可以先让外部 AI 客户端基于 MCP 读取到的文献信息进行总结。

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

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

建议按下面顺序处理：

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

高级配置

默认地址

红豆 MCP 默认地址为：

http://127.0.0.1:23119/mcp

其中 127.0.0.1 表示本机，23119 是红豆本地 HTTP 服务默认端口，/mcp 是 MCP 端点。

Codex 手动配置

Codex 配置文件通常位于：

~/.codex/config.toml

可加入：

[mcp_servers.hongdou]
type = "http"
url = "http://127.0.0.1:23119/mcp"

保存后，重启 Codex。

通用 JSON 配置

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

{
  "mcpServers": {
    "hongdou": {
      "type": "http",
      "url": "http://127.0.0.1:23119/mcp"
    }
  }
}

也有客户端使用 serverUrl、httpUrl 等字段名。实际字段以对应客户端文档为准。

Claude Code 项目配置

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

{
  "mcpServers": {
    "hongdou": {
      "type": "http",
      "url": "http://127.0.0.1:23119/mcp"
    }
  }
}

把 .mcp.json 放在项目根目录后，在该目录启动 Claude Code 时，就可以加载红豆 MCP。

配图建议

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

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

小结

红豆 MCP 的核心价值是让 AI 助手从“只能聊天”变成“可以帮你操作红豆文献库”。只要红豆保持打开，MCP 服务已启用，并且 AI 客户端适配成功，就可以在 Codex、necode 或其他支持 MCP 的客户端中，用自然语言完成文献搜索、PDF 阅读、笔记生成、在线导入和同步检查等任务。

文档更新时间: 2026-06-09 16:01 作者：管理员

红豆mcp使用帮助