openalex-mcp-server

---

概览

来自 OpenAlex 的学术目录数据——超过 2.7 亿篇作品、9,000 多万位作者、10 万多个来源，以及机构、主题、关键词、出版商和资助方。可跨全部八种实体类型搜索、筛选和汇总，将不明确的名称解析为规范 ID，并逐跳遍历引文图谱。

工具

工具	描述
openalex_search_entities	跨全部 8 种实体类型搜索、筛选、排序或按 ID 检索
openalex_analyze_trends	按组汇总，以分析趋势和分布
openalex_resolve_name	将名称或标识符（DOI、ORCID、ROR、PMID、ISSN、OpenAlex ID）解析为 OpenAlex ID
openalex_get_citation_graph	从种子作品开始逐跳遍历引文图谱：cites、cited_by 或 related_to
openalex_describe_fields	列出某实体类型有效的筛选、分组和选择字段名称

提示词

提示词	描述
openalex_literature_review	指导系统性文献检索：拟定查询、搜索、筛选、分析引文网络并综合研究结果
openalex_research_landscape	分析某个主题的研究概况：产出趋势、顶尖作者／机构、开放获取比例和资助来源

功能参考

openalex_search_entities _工具

• 按 ID 检索单个实体——OpenAlex ID、DOI、ORCID、ROR、PMID、ISSN 或 PMCID（裸值或 URL 形式，包括 OpenAlex 记录页和 API URL，例如 https://openalex.org/works/W2741809807），或按 slug 或关键词 URL 检索关键词。在 entity_type: "funders" 下，基金会的 Crossref Funder Registry DOI（10.13039/…）会通过仅返回一个结果的列表请求解析。OpenAlex 不对按 ID 查询收费，但有三个例外，按一次列表调用收费：按 slug 或 URL 查询关键词、id 中包含超出标识符本身的字符（W2741809807#x 仍会返回 W2741809807），以及该基金会 DOI 请求。id 优先：与其同时传入的搜索参数会被丢弃，响应会指出哪些参数被丢弃。OpenAlex ID 的字母表示的实体类型与 entity_type 不同，则会在发起任何上游调用前以 id_type_mismatch 失败；id 中包含 . 或 .. 路径段（原样或百分号编码）则会以 id_dot_segment 失败；标识符中的 ?、#、\、制表符或换行符会作为标识符的一部分进行百分号编码（SICI DOI 以 # 结尾）。PMCID 无法解析（OpenAlex 不索引 PMCID）——请改用作品的 PMID 或 DOI
• 关键词搜索（布尔运算符、带引号的短语、通配符、模糊匹配），以及 exact 和 semantic 搜索模式——semantic 会以约 1 次请求/秒的速度对依赖于查询的候选集进行排序（每页最多 50 条），其 meta.count 报告的是候选项数量，而非匹配总数
• filters 接受记录对象或无歧义的原生字符串（"issn:0920-8542"），也接受通过 filter 别名传入。转换情况会在 notice 中说明；成对双引号之外的逗号用于分隔子句，第一个冒号用于分隔键和值，同时保留 DOI/URL 中的冒号以及带引号的逗号短语。拒绝完全重复的键、裸片段和未配对引号，并提供恢复为记录形式的指导。记录中的每个键只能有一个值；指向同一上游字段的不同别名仍会以 AND 组合。设置 OPENALEX_FILTER_STRING_INPUT=false 可要求使用记录对象。原生字符串仅适用于此工具的 filters；公开的 schema 仍采用记录形式
• 在所有四个接受 filter 的工具中，未加引号传入的 filter 值必须使用成对双引号（unmatched_quote_in_filter_value）；引用筛选器会在种子查询之前检查。"graph neural" networks 这样的配对搜索短语仍然有效，包括 .search.exact。即使值使用了双引号，也不能在其中包含自己的内部双引号（quote_in_filter_value）
• 丰富的 filter 语法：字段之间使用 AND，字段内使用 OR（|）、AND（+）、NOT（!）、范围和比较。一个值不能同时包含 | 和 AND 运算符——+，或 ID、代码、language 键上的值之间的空格（语言名称中的空格属于名称的一部分；在国家字段中，空格始终属于国家名称，不表示 AND：DE US|FR 会以 invalid_country_code 失败）：OpenAlex 会先按 | 拆分值，并丢弃每个 AND 了多个值的备选项，因此 DE|FR+US 和 authorships.author.id: A1 A2|A3 都会在发起任何请求前以 mixed_and_or_in_filter_value 失败——请将 AND 放在第二个键中（在 works 上，将 institutions.country_code: US 与 authorships.institutions.country_code: DE|FR 并列）。自由文本搜索 filter（任何 .search 键——title.search、abstract.search.exact、title_abstract_keywords.search）或 OpenAlex 按整段文本匹配的字段（见下文）中的逗号会作为短语的一部分加上双引号；其他任何 filter 值中的逗号都会以 comma_in_filter_value 失败（OR 请使用 |）。在 .search 值中，DOI、日期（时间戳中的 +00:00 时区偏移）、URL（landing_page_url，不包括布尔值 has_pdf_url）、精确匹配的名称（display_name、awards.funder_display_name——C++、Erasmus+）、biblio 字段（期号 1+2）或 awards.funder_award_id 中的 + 是字面字符；对于 OpenAlex 按整段文本匹配的字段（display_name、awards.funder_display_name、awards.funder_award_id、geo.city、geo.region、raw_affiliation_strings、block_key、biblio 字段），包含空格的值会加上双引号，从而作为一个短语匹配（awards.funder_display_name: National Science Foundation）——! 和 | 仍然有效（geo.city: New York|Boston），但 + 不能在同一字段中将其与另一个值进行 AND 组合。这类值中的逗号也属于值的一部分（raw_affiliation_strings: Associazione Meteonetwork OdV, Milano, Italy）：包含逗号的值会加上引号，其中的 + 作为字面字符处理。以这种方式加引号的值，或任何非自由文本搜索 filter 中由你自行加上双引号的值，其外层引号内部不得包含双引号，否则会以 quote_in_filter_value 失败
• 国家和语言的值会转换为 OpenAlex 存储的代码；此规则适用于此处及其他所有接受 filters 的工具：对于国家字段（键名以 country_code、country_codes 或 countries 结尾），ISO 3166-1 alpha-3 代码、数字代码或英文名称——ISO 名称，或 OpenAlex 自身国家 facets 显示的名称（Russia、Ivory Coast、Trinidad & Tobago）——都会转换为 alpha-2 代码（DEU、276、Germany → DE），UK 会转换为 GB；无法识别为国家代码的值（Germanyy、999、unknown，或以空格连接的两个代码 DE US）会以 invalid_country_code 失败，且不会发送 filter。对于 language，ISO 639-2 代码会转换为 ISO 639-1 代码，英文名称会转换为其代码（eng、English → en；Cebuano → ceb）。每个 |/+ 段都会单独去除空格并转换，因此多词名称会作为一个值处理（South Korea|Japan → KR|JP、Scottish Gaelic|English → gd|en）；其他任何值——null、XK、ceb、zh-cn、countries/DEU 路径形式——则按原样发送
• select 默认返回按实体类型整理的字段，除非另行指定；也可使用 ["*"] 获取完整记录。无效字段名会报错并列出有效字段。在 works 上，author_list 按 authorship 顺序返回每位作者的 {id, display_name, orcid}——大小约为 authorships 的十分之一；后者还包含机构和隶属关系。author_list 永远不会包含在默认字段或 ["*"] 中
• 关键词和精确搜索支持游标分页，每页最多 100 条（默认 25 条）；semantic 搜索则使用 page（从 1 开始）遍历候选项。在 search_mode 不匹配时混用任一分页参数，会在上游调用前被拒绝
• sample（最多 100 条，仅限单页——cursor 和 page 均不适用）以及用于可重复随机抽样的确定性 seed；仅适用于关键词和精确模式，且不能与 sort 同时使用——OpenAlex 不会对 semantic 搜索进行抽样，并会拒绝排序抽样，因此这两种组合都会在上游调用前被拒绝
• 每个响应在每个呈现面中最多为 64,000 字节（structuredContent，以及包含其尾部内容的 content[]），除非最少可返回内容本身就超过此限额；此时会标记为 over_budget：超限页面会保留开头的完整记录，并在 omitted 中列出其余记录以及可一次性取回这些记录的调用（作为集合，按 OpenAlex 顺序排列），且不会影响 next_cursor；如果单条记录本身过大，则会对其最大型数组进行窗口化填充，使每个数组尽可能多地显示可容纳的内容，并标明其中包含的数组内容量；使用 id 查询时，slice: {field, offset} 可将任意数组分页至末尾
• 列表记录中恰好包含 100 条 authorships 或 author_list 项时，会标记为可能已截断；可使用 id + slice 调用获取更多已存储作者。单条查询和快照中，每篇作品最多保留 5,000 条 authorships；达到此上限后，每次 slice 中的两个作者字段仍都会标记为可能已截断。total 计数的是已存储条目，而非完整署名列表；这些条目全部读完后，next 会变为 null。其他 OpenAlex 获取操作或快照无法恢复超过存储上限的作者
• 对搜索/引用的正整数 per_page 超过 100，或对分析超过 200 时，会自动限制为最大值，并在 notice、日志和计数器中注明请求值和实际应用的大小。设置 OPENALEX_CLAMP_PER_PAGE=false 可恢复为超过公开最大值时拒绝请求。零、负数、小数、超过 50 的 semantic 搜索及超大抽样仍会被拒绝。id 查询会忽略页面大小，而 sample 会覆盖该值
• 未命名记录的 display_name 可为 null；每次调用都会报告 OpenAlex 每日预算的费用和剩余余额

---

openalex_analyze_trends _工具

• 按任意受支持的字段分组，以进行趋势、分布或比较分析；可与 filters 结合，在聚合前限定总体范围
• 每页最多 200 个分组（默认值）。不提供游标时，order: "count"（默认值）按数量返回排名靠前的 N 个分组，不提供后续页面；order: "key" 按键升序枚举不同值，并使用游标分页。布尔字段即使设置 "key"，仍按数量排序，且不支持游标分页。提供 cursor 后，即使省略 order 或设置为 "count"，也会选择按键排序。OpenAlex 按键排序遍历时可能跳回较早的分组：如果某页的首个键重复出现在更早的页面中，或者某页不满或为空，即使仍存在 next_cursor，也应停止遍历
• include_unknown（默认值 false）会为分组字段没有值的实体添加一个分组，并标记为 is_unknown: true，在文本输出中标示为未知。group_by 中的原生 :include_unknown 后缀也会启用此功能，即使显式设置为 false；同时传入两者时，后缀只会添加一次。OpenAlex 会将其键设为 -111/-111.0（数值字段）、unknown（文本字段和 order: "key"），或以 /unknown 结尾的 ID；该键是哨兵值，不是筛选值。布尔字段没有此类分组——缺失值计为 false
• key_display_name 始终存在，但当 OpenAlex 未提供标签时，其值可能为 null；在这种情况下，文本输出会显示分组键，包括未知值分组
• 并非所有字段都可用于分组——原始日期字段、.search 运算符、from_*/to_* 范围修饰符、fwci 等小数评分、display_name、doi 等外部 ID 字段，以及 OpenAlex 从相关实体查询的字段（例如 primary_location.source.country_code）都会被拒绝；openalex_describe_fields(entity_type, "group_by") 会列出可用于分组的字段
• 对 works 使用 group_by 分组 authorships.countries 时，提示会说明 OpenAlex 对该字段每篇作品仅统计前 100 个作者署名，并指出 authorships.institutions.country_code 是统计全部作者署名的字段
• 报告 OpenAlex 每日额度的费用和剩余余额——聚合的定价远低于对相同实体进行分页查询的费用

---

openalex_resolve_name _工具

• 输入名称或部分名称时，会执行自动补全搜索：最多返回 10 个匹配项，并提供消歧线索（最近所属机构、主办组织、地点等）
• 输入标识符——OpenAlex ID、DOI、ORCID、ROR、PMID、ISSN 或关键词 URL，无论是裸值还是 URL 格式——都会直接解析到其所指向的记录，并按所属实体类型返回。一个 ROR 可以同时对应某个组织的机构、资助方和出版商记录：未设置 entity_type（或设置为其他类型）时，会并行查询这三种类型，每种均为不计费的单条记录查询，并返回所有找到的记录，机构记录优先；entity_type 为 institutions、funders 或 publishers 时，则只查询对应类型。Crossref Funder Registry DOI（10.13039/…）会解析为资助方，除非 entity_type 为 works。系统可识别 PMCID，但不会解析出任何结果——OpenAlex 不索引 PMCID
• 短名称可能与 OpenAlex ID 的格式相同（关键词 p53 会被识别为出版商 P53），因此，无法解析的裸 OpenAlex ID 接下来会作为名称搜索，并遵循给定的 entity_type；提示信息会说明这两种查询结果。真实的 ID 仍只需一次请求即可解析。在 entity_type: "keywords" 下，系统从一开始就会将该格式作为关键词名称搜索
• filters 仅用于缩小自动补全范围，且必须指定 entity_type——名称查询若传入 filters 却未指定 entity_type，会在发出任何请求前被拒绝（filters_without_entity_type）。查询标识符时会忽略 filters，并在提示信息中说明；若名称搜索在 filters 限定范围内无匹配项，系统会回显这些筛选条件，并建议先放宽条件
• 设置 entity_type 后，若名称超过 1,000 个字符，OpenAlex 自动补全会失败；此类失败只报告一次，错误为 query_too_long，并建议缩短名称，不会作为服务中断重试
• 报告 OpenAlex 每日预算的消耗和剩余余额

---

openalex_get_citation_graph _工具

• direction 用于设置关系方向：cites（引用种子文献的作品）、cited_by（种子文献自身的参考文献列表）、related_to（OpenAlex 算法生成的相关作品，通常约为 8-30 篇，也可能为空）
• seed_id 接受 OpenAlex 作品 ID（裸值，或 OpenAlex 记录页 URL、API URL）、DOI 或 PMID（可识别 PMCID，但不会解析出任何结果）；系统会先通过实时查询进行验证，因此不存在的种子会报错 NotFound，而不是返回空图；其他实体类型的 ID 则会在任何上游调用前报错 id_type_mismatch
• 可结合 filters／sort／select（包括 author_list）缩小图范围；filters 不能设置 cites／cited_by／related_to，也不能设置这些键的别名（例如 cited_works）——这些键为 direction 保留
• 使用游标分页，每页最多返回 100 个结果（默认 25 个）
• 与 openalex_search_entities 相同的 64,000 字节响应预算和 100 位作者上限说明；从页面中截去的作品会按 OpenAlex 的顺序列在 omitted 中，并注明返回这些作品的 openalex_search_entities 调用
• 报告 OpenAlex 每日预算消耗，包括种子验证查询和图谱页面查询的费用，以及剩余余额

---

openalex_describe_fields _工具

• 列出实体类型和上下文（filter、group_by、select）的所有有效字段名称——完整集合，绝不截断
• group_by 是从筛选字段集合中剔除 OpenAlex 拒绝作为聚合键的字段后所得：原始日期字段、.search/.search.exact 运算符、from_*/to_* 范围修饰符，以及通过将每个列出的字段按实体类型分组并查询实时 API 得到的一组字段，其中包括 fwci 等小数评分、若干来源年份字段、display_name 和外部 ID 字段
• created_date、updated_date 及其 from_/to_ 形式虽列为可筛选字段，但 OpenAlex 仅向付费计划用户提供；没有付费计划时，对这些字段的筛选会在首次请求时失败，并返回 upstream_plan_required，且不会重试
• 可选的 query 会根据名称相似度重新排列结果，但不会删除任何字段——嵌套值的父对象仍可在列表靠后的位置找到
• 基于生成的字段目录，不会调用实时 API

---

openalex_literature_review _提示词

• 参数：必填的 topic；可选的 scope（narrow / broad），默认为 narrow
• 返回一条用户消息，按 6 步工作流展开：解析实体、搜索文献、识别关键论文、追踪引用、分析研究概况、综合发现
• scope 会改变搜索步骤：narrow 倾向于使用精确搜索和严格的主题筛选条件；broad 则会通过多个相关主题 ID 增加语义搜索

---

openalex_research_landscape _提示词

• 参数：必填的 topic
• 返回一条用户消息，按 7 步定量工作流展开：解析主题 ID、分析数量趋势、梳理主要贡献者（机构／国家／期刊）、开放获取率、资金来源、被引最多的作品、前沿新兴领域
• 资金来源步骤按 funders.id 分组，统计每个列出资助方的作品数量，并以资助方名称标记每个分组；对于奖项编号等具体资助项目级别的问题，应使用 awards.* 字段

功能

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

OpenAlex 专属功能：

• 类型化 API 客户端，可自动规范化 ID（DOI、ORCID、ROR、PMID、PMCID、ISSN、OpenAlex 记录页和 API URL，支持 http、https 或无协议前缀）；PMCID 会被规范化，但无法解析到任何内容，因为 OpenAlex 不索引 PMCID
• 默认无需密钥——可选的 API 密钥可提高速率限制和每日预算，可选的 mailto 可向 OpenAlex 的礼貌访问池标识调用者
• 将 HTTP 状态码映射为特定的 MCP 错误类（400 → InvalidParams；语义搜索的查询嵌入在上游失败时则为 ServiceUnavailable；422 → ValidationError；429 → RateLimited；若 429 表示拒绝付费计划筛选条件，则为 Forbidden），并显示上游消息
• 请求重试可感知超时，并通过 AbortSignal 支持取消

便于 Agent 使用的输出：

• 来源信息——每个调用 API 的工具都会报告 OpenAlex 每日预算的花费、剩余余额和重置时间（budget.costUsd、remainingUsd、resetsInSeconds）
• 有效查询回显——搜索、趋势和引文图响应会回显实际执行的条件，让你无需重新查看请求，就能诊断为何结果为空
• 判别式输出契约——类型化错误原因（entity_not_found、upstream_budget_exhausted、semantic_per_page_cap、reserved_filter_key 等）均附带明确的恢复提示
• 响应整形——摘要会从 OpenAlex 的倒排索引编码还原为纯文本；对于无标题或副文本记录，display_name 会保持为 null，而不会填充其他内容
• 干净的提供方文本——OpenAlex 会原样传递标题、摘要和名称，不进行消毒处理；HTML 实体会根据完整的 WHATWG 表解码，注释和 HTML/JATS/MathML 格式标记会被移除，CDATA 包装以及 IOP 的 <?CDATA …?> 数学标记会被去除，同时保留其中的 TeX，MathType 方程块（% MathType!MTEF!…!44A1!）会被移除，同时保留用于重述它们的 TeX；双重转义的换行符（字面上的 \n）会变为空格；A < B、95% CI 等字面文本以及 \nu 等 TeX 都会保留。标识符和 URL 字段（id、doi、ids、orcid、ror、issn、*_url、lineages）会按 OpenAlex 存储的内容原样返回，因此再次传入时都能解析。文本输出会对这些文本进行 Markdown 转义，因此孤立的 *、<tag> 或 [x](y) 会按原样显示；ID 以及渲染为链接的 URL 则保持字节级一致

开始使用

连接到托管实例，无需安装：

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

或者在本地运行：

claude mcp add openalex-mcp-server -- npx -y @cyanheads/openalex-mcp-server

对于其他客户端，将以下内容添加到 MCP 配置文件中：

{
  "mcpServers": {
    "openalex-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/openalex-mcp-server"]
    }
  }
}

可选的 OPENALEX_API_KEY——免费的 OpenAlex 账户密钥——可提高速率限制和每日预算，相较于匿名访问；OPENALEX_MAILTO 可向 OpenAlex 的礼貌访问池标识你的身份。Docker 或源码构建方式请参阅运行服务。

配置

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto（解析为 stateful）。服务端在代码中声明为 stateless；显式设置的值会覆盖该声明。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_ALLOWED_ORIGINS	HTTP 传输的浏览器 Origin 标头允许列表，以逗号分隔。未设置 = 仅允许回环地址；设置为 * 可禁用此限制。	仅允许回环地址
MCP_LOG_LEVEL	日志级别（RFC 5424）。	debug
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端。	in-memory
OPENALEX_API_KEY	OpenAlex 账户 API 密钥，将作为 api_key= 发送至上游（可在 openalex.org/settings/api 免费获取）。未提供时，将采用匿名速率限制。	—
OPENALEX_MAILTO	作为 mailto= 发送至上游的电子邮箱，用于向 OpenAlex 表明身份（“礼貌池”）；这是一个礼貌性标识，与 API 密钥分开。	—
OPENALEX_BASE_URL	OpenAlex API 基础 URL。	https://api.openalex.org
OPENALEX_FILTER_STRING_INPUT	允许在 openalex_search_entities 中使用明确无歧义的原生筛选字符串。设为 false 时，必须使用记录对象；无效的布尔值会导致启动失败。	true
OPENALEX_CLAMP_PER_PAGE	将过大的正整数 per_page 限制到上限，并显示请求值与应用值（搜索/引用为 100，分析为 200）。设为 false 可恢复拒绝超过已公布上限的值；无效的布尔值会导致启动失败。语义上限和样本上限仍会拒绝超限值。	true
OTEL_ENABLED	启用 OpenTelemetry 插桩（跨度、指标、完成日志）。	false

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

运行服务端

本地开发

需要 Bun v1.4.0 或更高版本（或 Node.js v24+）。

• 克隆并安装：

  git clone https://github.com/cyanheads/openalex-mcp-server.git
  cd openalex-mcp-server && bun install
  cp .env.example .env   # optionally set OPENALEX_API_KEY
  

• 构建并运行：

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

• 运行检查和测试：

  bun run devcheck   # Lints, formats, type-checks
  bun run test       # Runs the test suite
  

Docker

docker run --rm -e OPENALEX_API_KEY=your-key -p 3010:3010 ghcr.io/cyanheads/openalex-mcp-server:latest

镜像默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/openalex-mcp-server。如需通过 MCP 客户端使用 stdio 运行，请使用 "command": "docker" 和 "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/openalex-mcp-server:latest"]。如需在本地构建，请运行 docker build -t openalex-mcp-server .；默认会安装 OpenTelemetry 对等依赖项，若要省略这些依赖项，请使用 --build-arg OTEL_ENABLED=false 进行构建。

项目结构

目录	用途
src/index.ts	createApp() 入口点 — 注册工具和提示词。
src/config/	使用 Zod 解析并验证服务端专用环境变量。
src/mcp-server/tools/definitions/	工具定义（*.tool.ts）。
src/mcp-server/prompts/definitions/	提示词定义（*.prompt.ts）。
src/services/openalex/	OpenAlex API 客户端、字段目录和领域类型。
tests/	单元测试和集成测试，结构与 src/ 对应。

开发指南

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

• 处理程序抛出异常，框架负责捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录日志，使用 ctx.state 存储数据
• 包装 OpenAlex 响应：验证原始负载 → 规范化为领域类型 → 返回输出架构；绝不伪造缺失字段
• 按实体筛选前，始终先通过 openalex_resolve_name 将名称解析为 ID

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。