orcid-mcp-server

---

概述

来自 ORCID 注册表的研究人员身份数据。搜索并消除作者歧义，根据档案、作品、任职关系、资助和同行评审记录整理研究人员档案，并将外部标识符关联到 Crossref、PubMed 或 arXiv。

工具

工具	描述
orcid_search_researchers	使用结构化字段参数（姓名、所属机构、关键词、ROR ID、DOI、PMID、资助编号）搜索 ORCID 注册表
orcid_get_profile	获取研究人员的公开档案——姓名、其他姓名、个人简介、关键词、研究人员 URL、外部标识符
orcid_get_works	分页获取研究人员的作品（出版物、数据集、软件、预印本）
orcid_get_work_detail	接受最多 1,000 个 put-code，获取前 100 个不重复作品，并返回待续处理的代码
orcid_get_affiliations	获取任职关系记录：工作、教育、会员资格等
orcid_get_funding	列出按组汇总的资助信息，或选择某项资助以查看其存档描述、金额和来源
orcid_get_peer_reviews	获取同行评审活动：召集组织、评审者角色、评审类型
orcid_get_research_resources	列出研究资源——计算资源配额、设备使用权限、实验室设施
orcid_resolve_researcher	将有歧义的作者姓名消歧为按排名排序的已验证 ORCID iD 候选列表

资源

资源	描述
orcid://researcher/{orcid_id}/profile	研究人员个人资料（个人信息部分）——姓名、其他姓名、简介、关键词、外部 ID
orcid://researcher/{orcid_id}/works	研究人员的作品列表——前 25 项及总数

所有资源数据也可通过工具访问。将稳定的研究人员背景信息注入提示词时，请使用资源；需要筛选或处理结果时，请使用工具。

能力参考

orcid_search_researchers _工具

• 结构化参数——given_name、family_name、affiliation、keyword、ror_id、doi、pmid、grant_number——会自动以 AND 组合；query 会添加原始 Solr 语法——如果它是唯一字段，则按原样发送；否则会作为一个带括号的整体与其他字段进行 AND 组合，以保留顶层 OR 的各个备选项（仅包含排除条件的查询，例如 -keyword:x，会以不加括号的形式进行 AND 组合，因为 ORCID 不会匹配仅包含排除条件的组合）
• 至少一个参数必须非空白——空值或仅含空白字符的搜索会被拒绝，而不会针对整个注册库执行
• given_name 按词组匹配，但仅由首字母组成的值（J.、J. A.）会匹配以每个字母开头的名字
• doi 和 pmid 会映射到 doi-self / pmid-self 字段查询——查找将特定作品关联到其 ORCID 记录的研究人员。接受 URL 和标签形式（https://doi.org/…、doi:…、https://pubmed.ncbi.nlm.nih.gov/…/、PMID:…），并会将其转换为不带前缀的标识符，同时保留大小写。非空白值必须包含完整的 DOI（10. 后接数字、/ 和非空白后缀）或数字 PMID；格式错误或仅含前缀的值会在发送请求前失败。省略的字段或确实为空白的字段保持未设置状态
• ror_id 可采用不带前缀的 ROR ID（00f54p054）或 ror.org URL（https://ror.org/…、ror.org/…、带 www. 的主机名、末尾带斜杠），大小写均可；并会转换为 ORCID 索引的 https://ror.org/<lowercase id> 格式。若值不是 ROR ID，或其校验位不匹配，则会在执行任何搜索前被拒绝
• grant_number 会对研究人员资助项目中的资助编号进行不区分大小写的词组匹配，匹配范围为连字符、斜杠等分隔符之间的部分——5F31MH010500 也会匹配 5F31MH010500-03，但截断部分编号不会匹配任何结果——请搭配 orcid_get_funding 检查每个匹配项
• rows：接受 1–10,000（默认值为 20），获取前上限设为 1,000；两个界面都会通过提示告知请求数量和实际生效的上限。start：0–10,000 的偏移分页（ORCID 公共 API 对未经身份验证的请求设置的上限）
• 如果某一页的结构化输出或文本将超过 64,000 字节，也会提前停止，因此返回的 rows 可能少于请求数量；nextStart 会从第一个未返回的结果继续
• 返回包含内嵌姓名和机构数据的扩展搜索结果——进行基本发现时无需再获取个人资料
• 用于精确的字段限定查询；对于需要按排名消歧的模糊姓名，请使用 orcid_resolve_researcher

---

orcid_get_profile _工具

• 接受不带前缀的 ORCID iD（0000-0001-2345-6789）或 orcid.org URI（https://orcid.org/…、orcid.org/…、带 www. 的主机名、末尾带斜杠）；小写校验位 x 会规范化为 X。所有接受 orcid_id 的工具都接受相同格式；orcid://researcher/{orcid_id}/… 资源接受不带前缀的 iD
• 在一次响应中返回姓名、其他姓名（曾用名、转写形式、姓名首字母形式）、个人简介、关键词、研究人员 URL、外部标识符（Scopus Author ID、ResearcherID、Loop 等）、电子邮件地址和国家代码
• 仅返回公开可见的字段；研究人员可控制各字段的可见性。notice 会列出没有公开数据的所有部分（例如“没有公开的电子邮件地址或国家/地区”），因为空白部分可能是私密的，而非没有数据
• 在获取作品或所属机构前，用于构建研究人员档案的入口

---

orcid_get_works _工具

• 默认返回前 50 项作品（limit 接受 1–10,000，实际最大值为 1,000；达到上限时两个界面都会显示提示）；使用 offset 翻页，并读取返回的 nextOffset；workCount 报告可用作品总数
• 如果结构化输出或文本超过 64,000 字节，也会提前结束当前页，因此 returnedCount 可能小于 limit；无论哪种情况，truncated 和 nextOffset 都会提供续读信息
• 将 include_external_ids 设为 false，即可省略 DOI/PMID/arXiv/ISBN 标识符列表，减小载荷
• 每个 ORCID 作品组返回一条记录；其中的标识符属于该组，包括首选版本的标识符，以及其他来源持有的标识符，例如与 Crossref DOI 并列的 PMID
• 外部标识符已预先格式化，可用于链接到 Crossref、PubMed 或 arXiv
• 仅返回摘要；传入作品的 putCode 到 orcid_get_work_detail，即可获取摘要和贡献者列表
• 每项作品都会列出其 sources，即研究人员或 Crossref、大学系统等成员组织；selfAsserted 用于标记由研究人员自行声明的信息；列表为空并不意味着没有出版物

---

orcid_get_work_detail _工具

• put_codes：每次调用接受 1–1,000 个原始代码（来自 orcid_get_works）；获取前会按首次出现的顺序去重，并在一次请求中处理前 100 个不同代码；达到输入上限时，提示会指出该上限
• 返回摘要、带 CRediT 角色的贡献者、记录的外部 ID、引文元数据（BibTeX 或其他已存档格式）、期刊名称和 URL
• 如果记录列出的贡献者超过 100 人，则保留前 100 人和研究人员本人的条目（按 ORCID iD 匹配），并通过 contributorCount 和 contributorsTruncated 标记截断；超过 8,192 字节的引文会被省略并标记为 citationOmitted，以便大型合作论文可与其他记录一并返回
• 每个 put-code 对应一项作品的某个来源版本，因此其标识符可能少于 orcid_get_works 为该作品组列出的数量；sources 会指出该来源
• 单个 put-code 的失败（未找到或无法访问）会作为 errors 条目返回，其余批次仍会正常处理
• 持续添加记录，直到结构化输出或文本超过 64,000 字节，同时为所有续读元数据和提示预留空间。deferredPutCodes 包含所有尚未由已纳入的作品或已标明的错误处理的不同请求代码，按请求顺序排列，其中包括超出输入上限的代码或上游响应中缺失的代码；将其作为 put_codes 传入另一轮调用。提示会区分各类原因
• 上游限流会以 RateLimited 错误呈现；如果 ORCID 提供了 retryAfter，该错误会携带此信息

orcid_get_affiliations _工具

• types 用于筛选要返回的部分：employment、education、invited-positions、distinctions、memberships、qualifications、services 或 all — 默认返回 employment + education；不接受显式传入的空列表
• 无论请求多少种类型，都只调用上游一次
• 每条记录都会返回组织名称、消歧 ID（ROR/GRID/Ringgold）、部门、职务和日期范围
• 每条记录的 sources 会注明是谁添加了该记录 — 研究人员，或大学研究信息系统等成员组织；结果为空并不代表没有任职关系

---

orcid_get_funding _工具

• 不提供 put_code 时，会通过一次请求返回完整的分组资助列表，并使用 view: summary；每个首选摘要都会公开其可选的 putCode
• 返回资助类型（grant、contract、award、salary-award）、资助方名称及消歧 ID（Crossref Funder ID/ROR）、资助编号和资助期限
• 每个 ORCID 资助组只返回一条记录，取自其首选版本 — 同一笔资助存入两次，在 fundingCount 中只计一次；如果组内版本记录了不同的资助期限（例如同一资助编号下的续期），periods 会列出每个期限
• 将摘要中的 putCode 作为 put_code 传入，以使用 view: detail：仅获取该条存入记录，并返回其自身的来源，以及可选的描述、URL 和 amount: { value?, currency? }。十进制文本会原样保留；缺失的金额和币种字段仍保持缺失
• 使用 description_offset 对存入记录的描述进行分页（默认值为 0，且必须提供 put_code），偏移量以 Unicode 码点计。每条资助记录在描述存在时都会附带 descriptionOffset 和完整的 descriptionLength，且仅在仍有剩余文本时提供 nextDescriptionOffset。使用该后续偏移量重复选择器；资助元数据会在每一页重复。文本以 JSON 字符串表示描述，因此原始 CRLF 换行符得以保留
• 两种完整详情输出的大小均不超过 64,000 字节，包含元数据和续页信息。budgetOverflow 会明确说明元数据或单个码点导致的例外；超大页面仍会推进偏移量。描述缺失、为空或偏移量超出末尾时，均不会提供续页信息。不同请求会读取当前的存入记录，因此两页之间若记录发生变更，它们并非固定快照
• 所选记录不可用时返回 funding_not_found，公开访问遭拒时返回 funding_inaccessible，未提供选择器却请求分页时返回 detail_required；每种错误都会说明如何恢复
• 资助信息由研究人员或成员组织（资助方、机构、搜索与关联工具）提供；每条记录的 sources 会注明来源。大多数确实获得资助的研究人员在此处没有记录；没有记录不代表没有资助

---

orcid_get_peer_reviews _工具

• 按上游顺序对历史记录分页，使用 offset（默认值为 0）和 limit（默认值为 50，接受的最大值为 10,000，实际最大值为 1,000）；如果限制值被调低，两种输出都会显示提示
• reviewCount 统计返回的评审记录数；totalCount 表示完整历史记录数。当 truncated 为 true 时，使用 nextOffset 继续。空页面和超出末尾的页面仍会保留总数，但不会提供续页信息
• 两种完整输出的大小均不超过 64,000 字节，包含提示和续页信息。若单条评审记录无法拆分且超出大小限制，则会单独返回，并明确提示这一例外；续页偏移量会越过该记录
• 每条记录返回评审者角色（reviewer、editor、chair 等）、评审类型、完成日期、以 ISSN 为键的分组标识符，以及召集组织的 ORCID
• 召集组织通常是导入评审记录的服务（Publons、Clarivate），而非期刊；ORCID 不返回期刊名称，因此 ISSN 是期刊标识，并会置于包含 ISSN 的每条评审记录的开头
• 评审记录由研究人员或导入记录的成员组织提供；每条记录的 sources 会注明来源。不同研究人员的记录覆盖情况差异很大

---

orcid_get_research_resources _工具

• 涵盖计算资源分配、设备使用权、实验室设施、数据资源和临床研究注册
• 这是 ORCID 中较新的、条目较少的部分——大多数研究人员没有任何条目，而没有条目并不意味着相关资源不存在
• 条目通常由资源分配系统（例如 ACCESS、XSEDE）提交，而非由研究人员添加
• 返回资源标题、托管组织（含消歧 ID）、外部标识符（通常为门户 URI）、访问期限，以及提交该条目的 sources
• 默认的 view: summary 会列出提案；proposalHosts 包含每个提案托管方，而 hostOrganization 为兼容性保留第一个托管方
• 对于 view: detail，请将提案的 putCode 作为 put_code 传入：每个条目都包含其名称、类型、hosts 中的所有运营方、外部标识符和 URL；提案来源信息保留在资源记录中
• 详情页使用 item_offset（默认值为 0）和 item_limit（默认值为 50，实际最大值为 100，接受的最大值为 10,000）；两者都需要 put_code。itemCount、returnedItemCount、itemOffset、itemsTruncated 和 nextItemOffset 描述当前页；顶层的 truncated 与 itemsTruncated 一致，itemLimitNotice 会在两个界面上说明已调低的限制
• 两种详情界面均限制在 64,000 字节以内，包含提案元数据和续页信息；从 nextItemOffset 处继续。对于无法拆分且超出限制的条目，会单独返回并附带 budgetOverflow；无法拆分的提案元数据也会获得明确的例外说明。空页面和超出末尾的页面不会提供续页信息

---

orcid_resolve_researcher _工具

• 返回按排名排列的候选项（rows 默认值为 5，接受范围为 1–10,000，各搜索阶段的实际最大值均为 20），并提供透明的消歧信号：姓名匹配类型（exact/partial/other-name/none）、机构重合标志和锚点类型（doi/pmid/none）。结果被截断时会提供提示，报告请求数量和实际数量，并附上无结果时的指导信息
• 姓名和机构比较不区分大小写和重音符号——José Baselga 和 Jose Baselga 会对同一候选项作出相同分类
• 提供 doi 或 pmid 时（可以是不带前缀的标识符，也可以是 URL），会使用 doi-self 或 pmid-self 作为锚点——将该作品关联到其 ORCID 记录的研究人员几乎可以确定是匹配项
• 接受完整姓名（Jennifer Doudna）、带首字母的署名（J. Doudna、Jennifer A. Doudna）或 姓, 名 格式（Doudna, Jennifer，按 Jennifer Doudna 读取）；如果候选项的第一个名字以给定首字母开头，该首字母会计入 partial 匹配
• 首先搜索完全匹配的姓名短语，因此按原样匹配的姓名只会发送一个查询。仅当较早阶段均无结果时，才会运行后续阶段：先搜索任意首字母对应的署名形式并附带机构信息，然后搜索不附带机构信息的姓名短语和署名形式，再搜索 ORCID 记录中列出的其他姓名，最后单独搜索每个提供的锚点
• 不生成合成分数——仅提供原始信号字段，以便调用方应用自己的排名逻辑

---

orcid://researcher/{orcid_id}/profile _资源

• 以 application/json 格式返回姓名、其他姓名、个人简介、关键词、研究人员 URL 和外部标识符
• {orcid_id} 是不带前缀的 iD，校验位可以是 X 或 x——URI 路径段不能使用 https://orcid.org/ 形式
• 与工具一样，出错时会返回带类型的 data.reason 和恢复提示：校验和无效的 iD 使用 invalid_orcid_id（在任何上游调用之前于本地拒绝）；ORCID 不认识的 iD，或没有公开姓名的记录，使用 profile_not_found
• 如果响应需要流入条件逻辑，优先使用 orcid_get_profile 工具

orcid://researcher/{orcid_id}/works _资源

• 以 application/json 格式返回前 25 条成果，以及 workCount（可用成果总数）
• {orcid_id} 为不带前缀的 iD，校验位可以是 X 或 x
• 校验失败时返回 invalid_orcid_id（在调用任何上游服务前检查校验和）；iD 不存在时返回 profile_not_found（包含 data.orcidId）。两种错误都会提供恢复提示
• 此资源不支持游标分页；如需分页获取完整列表或筛选结果，请使用 orcid_get_works 工具
• 响应中的 DOI 和 PMID 可直接用于 Crossref 或 PubMed 链式调用

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔的身份验证（none / jwt / oauth）、可替换的存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），并提供结构化日志和可选的 OpenTelemetry 跟踪。

ORCID 专属功能：

• 使用 ORCID Public API v3.0（https://pub.orcid.org/v3.0）——公共读取端点无需 API 密钥
• 以 expanded-search 作为主要搜索后端——直接返回 ORCID iD、姓名和机构数据，避免逐个获取个人资料造成的 N+1 次调用
• 查询隶属关系时只调用一次 /activities，再在客户端进行筛选——相比按分区获取，最多可减少 7 次并行上游调用
• 在成果响应中提供外部标识符（DOI、PMID、arXiv ID），格式可用于跨服务调用 Crossref、PubMed 或 arXiv
• 将成果标题、摘要以及资助和研究资源标题中存储系统留下的内联标记（<i>、<sup>、<h4>）剥离为纯文本；存储的引文则原样传递

便于 Agent 使用的输出：

• 来源信息——orcid_resolve_researcher 返回原始消歧信号（姓名匹配类型、机构重叠情况、锚点类型），而不是合成的置信度分数
• 明确每项内容由谁提供——六种活动工具返回的每条记录都带有 sources：添加该记录的个人或成员组织（如大学系统、资助方、Crossref、Web of Science），以及研究者是否确认了该记录（selfAsserted）；分组后的成果和资助会列出组内每项内容的来源
• 截断提示——orcid_search_researchers 会报告 numFound，并根据 ORCID Public API 的 10,000 偏移量上限标记 truncated；同时会将单页结果限制在 64,000 字节响应预算内，并提供用于继续获取的 nextStart。orcid_get_works 会根据自身的分页大小和 64,000 字节响应预算报告 workCount 和 truncated
• 隔离部分失败——orcid_get_work_detail 会在成功解析的成果旁返回每个 put-code 对应的错误，而不是让整批请求失败，并会列出因响应预算限制而延后返回的 put-code
• 空结果指引——orcid_get_works、orcid_get_affiliations、orcid_get_funding、orcid_get_peer_reviews 和 orcid_get_research_resources 在结果为空时会返回提示，说明这可能意味着研究者或成员组织均未添加条目，或可见性设置将其隐藏，而非确认这些条目不存在；orcid_get_profile 会列出每个没有公共数据的分区
• 将记录文本标记为数据——在文本输出中，个人简介和摘要以引用块形式呈现；姓名、标题和组织名称保持在单行内；存储的引文则放在无法被其自身闭合的代码围栏中，因此研究者或存储系统编写的文本不会被误认为是服务自身的标题或标签；structuredContent 会逐字保留所有值

开始使用

公共托管实例

可通过 https://orcid.caseyjhand.com/mcp 使用公共实例，无需安装。该实例提供 Streamable HTTP；每种客户端都需要使用各自的配置格式。

对于 Claude Code：

claude mcp add --transport http orcid-mcp-server https://orcid.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "orcid-mcp-server": {
      "type": "streamableHttp",
      "url": "https://orcid.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "orcid-mcp-server": {
      "url": "https://orcid.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Settings → Connectors 下添加远程服务。

自托管 / 本地

将以下内容添加到 MCP 客户端配置文件中。无需 API 密钥 — ORCID Public API 开放供公众读取。

{
  "mcpServers": {
    "orcid-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/orcid-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "orcid-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/orcid-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "orcid-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/orcid-mcp-server:latest"
      ]
    }
  }
}

如需使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

先决条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需 API 密钥。ORCID Public API 开放供公众读取。根据 ORCID Public API ToS §2，仅限非商业用途。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/orcid-mcp-server.git

2. 进入目录：

cd orcid-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env if needed — no required vars

配置

启动时，所有配置都会通过 src/config/server-config.ts 中的 Zod schema 进行验证。主要环境变量：

变量	描述	默认值
ORCID_API_BASE_URL	覆盖 ORCID API 基础 URL。可用于指向沙盒（https://pub.sandbox.orcid.org/v3.0/）。	https://pub.orcid.org/v3.0
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_HTTP_ENDPOINT_PATH	HTTP 端点路径	/mcp
MCP_SESSION_MODE	HTTP 会话模式：auto、stateful 或 stateless。此服务在 createApp() 中声明为 stateless — 没有工具会在处理程序执行期间要求调用方提供输入 — 设置此变量后将覆盖该值。	stateless
MCP_PUBLIC_URL	用于 TLS 终止反向代理部署的公共源	none
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）	info
MCP_GC_PRESSURE_INTERVAL_MS	选择启用的 Bun 专用强制 GC 压力循环（毫秒）。如果持续 HTTP 负载下观察到堆增长，可尝试设置为 60000。	0（已禁用）
LOGS_DIR	日志文件目录（仅限 Node.js）	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1	in-memory
OTEL_ENABLED	启用 OpenTelemetry	false

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t orcid-mcp-server .
docker run --rm -p 3010:3010 orcid-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/orcid-mcp-server。默认会安装 OpenTelemetry 对等依赖项 — 构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口 — 注册工具和资源，初始化服务。
src/config	使用 Zod 解析并验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。包含搜索、消歧、个人资料、作品、作品详情、隶属关系、资助、同行评审和研究资源等领域的九个工具。
src/mcp-server/resources	资源定义（*.resource.ts）。包含个人资料和作品资源。
src/services/orcid	ORCID Public API v3.0 服务层 — 搜索、记录部分获取器、重试 / 退避。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要说明：

• 处理程序抛出异常，由框架捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 在 createApp() 数组中注册新工具和资源
• 封装 ORCID API 调用：验证原始响应 → 规范化为领域类型 → 返回输出 schema；切勿伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.