endnote-mcp

EndNote MCP

将 EndNote 参考文献库连接到 Claude AI。搜索参考文献、阅读 PDF、格式化引文、查找相关论文并生成参考书目——所有操作都可直接在 Claude Desktop 对话中完成。

功能介绍

设置完成后，你可以向 Claude 提出如下问题：

• “在我的文献库中搜索 social capital 和 Bourdieu”
• “查找关于组织如何应对不确定性的论文”（语义搜索）
• “查找与论文 #3844 相关的参考文献”
• “给出参考文献 #1234 的 APA 引文”
• “为参考文献 12、45、78、102 生成参考书目”
• “将参考文献 12、45、78 导出为 BibTeX”
• “阅读那篇 Smith 等人的论文第 5-7 页”

Claude 会搜索你的本地文献库——除了正常对话内容外，不会有任何内容上传到云端。

工作原理

EndNote Library → XML Export → endnote-mcp index → SQLite Database (FTS5 + Embeddings)
                                                          ↕
                                   Claude Desktop ← MCP Server (12 tools)

你的参考文献和 PDF 文本会被索引到本地 SQLite 数据库，并支持全文搜索。你也可以选择启用 AI 嵌入，以实现语义搜索——按含义而不仅仅是关键词查找论文。安装语义搜索依赖项后，索引过程中会自动为新参考文献生成嵌入。Claude 通过 Model Context Protocol (MCP) 连接。

要求

• EndNote 20+（任意版本）
• Claude Desktop 应用

下面的捆绑安装程序没有其他前置要求——Claude Desktop 会管理 Python 和依赖项。CLI 安装方式还需要 Python 3.10+ 和 uv（或 pip）。

安装（桌面捆绑包——推荐）

这是面向非技术用户的最快安装方式。无需 Python 或终端。

1. 从 EndNote 导出文献库。 File → Export → 选择 XML 格式 → 保存到 Desktop 等位置。
2. 下载 最新版本中的 endnote-mcp.mcpb。
3. 双击 .mcpb 文件（或者在 Claude Desktop 中选择：Settings → Extensions → Install Extension…）。
4. 在安装对话框中，指定以下文件夹：
   • 你的 EndNote XML 文件（来自第 1 步）
   • 你的 PDF 附件文件夹——通常是 .enl 文件旁边的 <library>.Data/PDF/，或 .enlp 包内的 PDF/。
5. 点击 Install。Claude Desktop 会自动开始为你的文献库编制索引——几秒钟内即可搜索元数据，PDF 文本和语义嵌入则会在后台处理完成。

就这么简单。试着问 Claude “在我的文献库中搜索 grounded theory”。

该捆绑包使用独立配置（config-mcpb.yaml），因此安装它不会影响现有的 CLI 设置。两者默认使用同一个数据库，所以如果你已经通过 CLI 创建了索引，捆绑包会复用该索引，而不会再创建一份。

自行构建捆绑包

维护者（或任何基于源代码进行开发的人）可以使用以下命令构建：

bash scripts/build_mcpb.sh
# → dist/endnote-mcp.mcpb

构建产物是一个跨平台的 .mcpb 文件（约 36 KB）。依赖项会在安装时通过 Claude Desktop 内置的 uv 运行时解析。

该格式此前名为 DXT，使用 .dxt 扩展名，后来在上游改名为 MCPB（MCP Bundles）。参见 modelcontextprotocol/mcpb。

安装（CLI / 从 PyPI 安装）

更喜欢使用终端？此方式会安装 endnote-mcp CLI，用于编制索引和生成嵌入。

1. 安装

# With uv (recommended)
uv tool install endnote-mcp

# Or with pip
pip install endnote-mcp

2. 从 EndNote 导出文献库

在 EndNote 中：File → Export → 选择 XML 格式 → 保存到方便的位置（例如 Desktop）。

3. 运行设置向导

endnote-mcp setup

向导将：

• 自动检测 XML 导出文件和 PDF 目录
• 创建配置
• 为文献库建立索引
• 自动配置 Claude Desktop

4. 重启 Claude Desktop

退出并重新打开 Claude Desktop。你会在 MCP 连接器中看到 “EndNote Library”。

Claude Code 插件和 Agent 技能

仓库中包含一项技能 endnote-library，用于教 Agent 如何使用你的文献库：仅引用工具返回的记录；页码以印刷页为准，而非 PDF 中的位置；逐字核对引文；并逐一验证草稿中的参考文献。

Claude Code。 先安装 CLI 并为文献库建立索引（上文步骤 1–3），然后运行：

/plugin install endnote --marketplace gokmengokhan/endnote-mcp

在低于 2.1.275 的 Claude Code 版本中，运行 /plugin marketplace add gokmengokhan/endnote-mcp，然后运行 /plugin install endnote@endnote-mcp。该插件会添加这项技能，并通过 endnote-mcp serve 启动服务，因此该命令必须位于你的 PATH 中。如果你已经通过 claude mcp add 和相同的命令添加了服务，Claude Code 只会连接一次；如果你使用的是其他命令或路径，请通过 claude mcp remove endnote 将其移除，以免出现重复工具。

Claude Desktop。 将 plugin/skills/endnote-library/ 文件夹压缩为 ZIP，并在 Customize > Skills 下上传。

其他 Agent。 能读取 Agent Skills（SKILL.md 文件夹）的 Agent 也可以使用同一项技能：将 plugin/skills/endnote-library/ 复制到 Agent 的技能目录中。

语义搜索（可选）

启用基于含义的搜索，即使参考文献使用的术语与你的查询不同，也能找到相关内容。例如，搜索 “公司如何为不确定的未来做准备”，可以找到关于情景规划和战略前瞻的论文。

# Install semantic search dependencies
pip install endnote-mcp[semantic]

# Generate embeddings (~3 min for 4,000 references)
endnote-mcp embed

此功能在本地使用轻量级模型 all-MiniLM-L6-v2，无需 API 密钥，所有数据都保留在你的设备上。

命令

命令	功能
endnote-mcp setup	交互式设置向导
endnote-mcp index	添加新参考文献后重新建立索引（增量式）
endnote-mcp index --full	从头完整重新建立索引
endnote-mcp index --skip-pdfs	仅为元数据建立索引（快速，约 1 秒）
endnote-mcp index --embed	重新建立索引并生成嵌入
endnote-mcp embed	生成语义搜索嵌入
endnote-mcp embed --full	从头重新生成所有嵌入
endnote-mcp status	显示索引统计信息
endnote-mcp install	添加到 Claude Desktop 配置
endnote-mcp serve	启动 MCP 服务（Claude Desktop 会自动使用）

Claude 可用的工具

工具	描述
search_references	按作者、标题、年份、关键词、摘要搜索（按 BM25 排序，附 DOI 链接）
search_fulltext	搜索 PDF 内容——查找概念、引文和方法
search_library	一次调用同时搜索元数据和 PDF
search_semantic	使用 AI 嵌入按含义搜索（需要 endnote-mcp[semantic]）
get_reference_details	获取参考文献的完整元数据（摘要、关键词、DOI 等）
get_citation	按 APA 7th、Harvard、Vancouver、Chicago 或 IEEE 格式生成引文
get_bibtex	将参考文献导出为 LaTeX 使用的 BibTeX 条目
get_bibliography	为多篇参考文献生成格式化书目
find_related	查找相似的参考文献（如果有嵌入则使用嵌入）
read_pdf_section	阅读 PDF 附件中的指定页面
list_references_by_topic	按主题广泛列出参考文献
rebuild_index	更新 EndNote 文献库后重新建立索引

添加新参考文献

向 EndNote 文献库添加新参考文献时：

1. 从 EndNote 重新导出 XML（覆盖同一文件）
2. 执行以下任一操作：
   • 在终端运行 endnote-mcp index，或
   • 向 Claude 询问：“重建我的文献库索引”

索引采用增量处理——只处理新的参考文献和 PDF，不会重新处理整个文献库。如果已安装语义搜索，新参考文献会自动生成嵌入向量。

性能

操作	耗时（4,000 条参考文献）
元数据索引	~1 秒
PDF 提取（首次）	每 100 个 PDF 约 1 分钟
PDF 提取（增量）	仅处理新 PDF
嵌入向量生成	~3 分钟
关键词搜索	< 50 毫秒
语义搜索	< 200 毫秒

配置

配置文件存储于：

• macOS：~/Library/Application Support/endnote-mcp/config.yaml
• Windows：%APPDATA%/endnote-mcp/config.yaml
• Linux：~/.config/endnote-mcp/config.yaml

endnote_xml: /path/to/your/library.xml
pdf_dir: /path/to/your/Library.Data/PDF
db_path: /path/to/library.db    # auto-set by setup
max_pdf_pages: 30                # max pages per read request
search_notes: false              # include the EndNote Notes field in searches

Notes 字段

默认会索引并搜索 EndNote 的Research Notes（研究笔记）字段——你可以在其中记录自己的摘要和判断；其排序优先级仅低于关键词，高于摘要。

普通的 Notes 字段也会被索引，但不会用于匹配，因为文献管理器在导入时会把它当作杂项信息的存放处，例如作者所属机构、电子邮件地址和主题词。设置 search_notes: true 即可将其纳入搜索。该设置立即生效——无需重新索引。

引用格式

内置五种格式：

• APA 第 7 版 — get_citation(rec_number=42, style="apa7")
• Harvard — style="harvard"
• Vancouver — style="vancouver"
• Chicago（作者-日期制，第 17 版）— style="chicago"
• IEEE — style="ieee"

使用 get_bibliography 一次性格式化多条参考文献，并按作者或年份排序。

BibTeX 导出

将参考文献导出为 BibTeX 条目，以便在 LaTeX 中使用：

• 向 Claude 询问：“将参考文献 42 和 100 导出为 BibTeX”
• 或直接使用 get_bibtex 工具，并提供以逗号分隔的记录编号

生成完整条目，包含正确的条目类型（@article、@book、@inproceedings 等）、引用键以及所有可用字段。

故障排除

“未找到配置” — 运行 endnote-mcp setup

“未找到 XML 文件” — 从 EndNote 重新导出：文件 → 导出 → XML 格式

“未找到 PDF” — 检查配置中的 pdf_dir 是否指向正确的 .Data/PDF 目录

搜索未返回结果 — 运行 endnote-mcp index 以重建数据库

Claude Desktop 未显示工具 — 运行 endnote-mcp install，然后重启 Claude Desktop

“语义搜索不可用” — 运行 pip install endnote-mcp[semantic]，然后运行 endnote-mcp embed

客户端报告服务“连接失败” / CONNECTION_CLOSED — 客户端会隐藏底层错误。运行 echo '' | endnote-mcp serve 以查看实际的回溯信息（之后打印的 JSON 解码错误只是由空输入导致，并非故障）。

发布

推送标签时会触发发布流程，见 .github/workflows/release.yml。该流程通过 OIDC 发布到 PyPI 和 MCP Registry，仓库中不会存储 API 令牌。

版本号共有七处，注册表会拒绝与已发布的 PyPI 版本不完全一致的 server.json。请更新所有版本号，然后在打标签前进行验证：

# pyproject.toml, server.json (x2), CITATION.cff, the README citation
# block, mcpb/manifest.json and mcpb/pyproject.toml
python scripts/check_version.py v1.4.12

git commit -am "Bump version to 1.4.12"
git tag v1.4.12 && git push origin main --tags

引用本软件

如果你在研究中使用了此工具，请引用：

Gokmen, G. (2026). EndNote MCP: Connecting EndNote Reference Libraries to Claude AI (Version 1.4.15) [Computer software]. https://doi.org/10.5281/zenodo.18617546

或者点击 GitHub 上的“引用此仓库”按钮，获取 BibTeX/APA 格式。

许可证

AGPL-3.0 — 可免费使用、修改和分发。详情请参阅 LICENSE。