# @cyanheads/openalex-mcp-server 中文文档

规范地址：https://npmcn.com/package/%40cyanheads/openalex-mcp-server/

版本：0\.11\.0
npm 元数据更新时间：2026-10-29T03:56:18.125Z
中文译文更新时间：2026-11-11T06:11:28.269Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cyanheads/openalex-mcp-server
原文对照：https://npmcn.com/package/%40cyanheads/openalex-mcp-server/?lang=original
项目主页：https://github.com/cyanheads/openalex-mcp-server#readme
源码仓库：https://github.com/cyanheads/openalex-mcp-server

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.1 MB，158 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24\.0\.0
- 运行依赖：3 个
- 首次发布：2026-03-24T11:43:57.683Z
- 最新版本发布：2026-10-29T03:56:17.885Z
- 近 30 天下载量：4020（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：53（近 12 个月 53 个）

## 中文简介

通过MCP访问OpenAlex学术研究目录——270M+出版物. (原始内容存档于2012-10-12). STIO or Streamable HTTP.

## 安装

```sh
npm install @cyanheads/openalex-mcp-server
```

也可以使用：`pnpm add @cyanheads/openalex-mcp-server`、`yarn add @cyanheads/openalex-mcp-server`、`bun add @cyanheads/openalex-mcp-server`

## README

# @ cyanheads/ openalex- mcp- server (中文(简体) )

**通过MCP访问OpenAlex学术研究目录——270M+出版物. (原始内容存档于2012-10-12). STIO or Streamable HTTP.**

5个工具 • 2个提示

[![Version](https://img.shields.io/badge/Version-0.11.0-blue.svg?style=flat-square)](https://npmcn.com/package/%40cyanheads/openalex-mcp-server/CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](https://npmcn.com/package/%40cyanheads/openalex-mcp-server/LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/openalex-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-%5E2.4.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/openalex-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openalex-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-%5E7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.4-blueviolet.svg?style=flat-square)](https://bun.sh/)

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/openalex-mcp-server/releases/latest/download/openalex-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=openalex-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvb3BlbmFsZXgtbWNwLXNlcnZlciJdfQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22openalex-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads/openalex-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

**公共主机服务器 :** [https://openalex.caseyjhand.com/mcp 页面存档备份,存于互联网档案馆](https://openalex.caseyjhand.com/mcp)

* * *

## 概览

学者目录数据来自 [打开亚历山大](https://openalex.org/) ——270M+作品,90M+作者,100K+来源,外加机构,专题,关键词,出版商,资助者,并获奖. 搜索、过滤和聚合到所有9个实体类型, 将模糊的名称解决为cononic ID, 然后一次一跳地走引用图.

### 工具

| 工具 | 说明 |
| :-- | :-- |
| `openalex_search_entities` | 搜索、过滤、排序或以ID检索所有9个实体类型 |
| `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` | 列出有效的过滤器, 组 by, 并为实体类型选择字段名称 |

### 提示

| 提示 | 说明 |
| :-- | :-- |
| `openalex_literature_review` | 为系统文献搜索提供指导: 制定查询、搜索、过滤、分析引用网络、综合发现 |
| `openalex_research_landscape` | 分析某一专题的研究情况:数量趋势、主要作者/机构、开放获取率、资金来源 |

服务器还发布代理技能, `openalex-guide` (单位:千美元)`skill://openalex-guide/SKILL.md`源代码 `skills/openalex-guide/`:哪个过滤键回答问题,如何读取 `group_by` 计数,每个ID类型来自何处, 以及如何在不选取名词的情况下给作者下针. 它在npm包,多克图像 `.mcpb` 捆绑和插件安装 .

## 能力参考

### `openalex_search_entities` 工具

-   通过 `id`: 一个 OpenAlex ID, DOI, ORCID, ROR, PMID, ISSN, 或 PMCID, 赤裸或作为 URL( OpenAlex 记录页和 API URL 等) `https://openalex.org/works/W2741809807` ),或按其 sattle 或 URL 键。 下 `entity_type: "funders"`,一个Crossref Funder Register Register DOI(`10.13039/…`也决定
    -   `id` 优先 : 丢弃与之相邻的搜索参数, 以及响应名称
    -   由 ID 查找的地址是未开票的, 除了关键字 sattle 或 URL, an `id` 字符超过标识符(`W2741809807#x` 仍然返回 W2741809807, 并有一个资助者 DOI, 每张账单作为一个列表调用
    -   在任何请求之前均以 `id_type_mismatch` (另一个实体类型的OpenAlex ID)或 `id_dot_segment` 联合国 `.` 或者说 `..` 路径段); a `?`, (中文(简体) ), `#`, (中文(简体) ), `\`,标签,或标识符内的换行符是%-编码的,所以SICI DOIs结束于 `#` 页:1
    -   PMCID 解决不了任何问题( OpenAlex Index no); 使用工作的 PMID 或 DOI
-   `entity_type: "awards"` 获得赠款`G…` 身份证) `openalex_resolve_name` 由于 OpenAlex 没有自动完成奖项,所以不抬头
-   关键词搜索(布尔运算符、所引用的短语、通配符、模糊匹配)+ `exact` 财务报告和审定财务报表 `semantic` 搜索模式——语义学将一个基于查询的候选者设置在~1 req/sec(每页最多50个),及其 `meta.count` 报告候选人数而不是对应总数
-   `filters` 接受记录对象或明确的本地字符串(`"issn:0920-8542"`,包括通过 `filter` 别名。 改划情况披露于 `notice`;外相对的逗号双引出单独的条款,而第一个冒号从它的值中分离出一键,保留了 DOI/URL 冒号并引用了逗号短语. 精确的重复密钥,赤出碎片,和无相匹配的引文被用记录式的回收指导来拒绝. 记录每个密钥有一个值;同一上游领域的独特别名仍然存在。 设定 `OPENALEX_FILTER_STRING_INPUT=false` 以要求记录对象。 原生字符串只适用于此工具的过滤器, 记录表保留了广告的图案
-   未引用的过滤器值必须在全部四个取取过滤器工具上配对双引号(`unmatched_quote_in_filter_value`); 种子检查前检查引用过滤器。 平衡搜索短语,例如 `"graph neural" networks` 仍然有效,包括 `.search.exact`。发送的双引号值仍然不能包含自己的内部双引号(`quote_in_filter_value`(中文(简体) )
-   丰富的过滤语法:和跨字段,或字段内(`|`),并且在一个领域(`+`),没有(`!`页:1
    -   一个值不能混合 `|` 带有(a)项 `+`,或ID或代码之间的空格 : OpenAlex会默默地放弃And-ed的替代品,所以 `DE|FR+US` 财务报告和审定财务报表 `authorships.author.id: A1 A2|A3` 失败为 `mixed_and_or_in_filter_value` 在任何请求之前 置入第二把钥匙(`institutions.country_code: US` 旁边 `authorships.institutions.country_code: DE|FR` (关于工作)
    -   字段 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`(三); `+` 和它与另一个价值
    -   允许逗号进入 `.search` 值和整文本字段; 其它失败之处为 `comma_in_filter_value` (使用时 `|` 其他资源)
    -   `+` 是一个字面字符 `.search` 值、 DOIs、 日期、 URL、 完全匹配的名称(`C++`, (中文(简体) ), `Erasmus+`, (中文(简体) ), `biblio` 字段(问题) `1+2`),以及 `awards.funder_award_id`
    -   引用的值中的双引号失败 `quote_in_filter_value`
-   国家和语言值转换为代码 OpenAlex 存储, 在每个工具中 `filters`数字 :
    -   国别领域(以 `country_code`, (中文(简体) ), `country_codes`,或 `countries`: ISO alpha-3代码,数字代码,和英文名称(ISO's 或 OpenAlex's own sacet 标签,例如: `Ivory Coast`)成为α-2(`DEU`, (中文(简体) ), `276`, (中文(简体) ), `Germany` → `DE`· ; `UK` → `GB`) (中文(简体) ). 无法成为国家的价值(`Germanyy`, (中文(简体) ), `999`, (中文(简体) ), `DE US`失败为 `invalid_country_code` 任何请求之前
    -   `language`: ISO 639-2代码和英文名称成为ISO 639-1 (`eng`, (中文(简体) ), `English` → `en`· ; `Cebuano` → `ceb`(中文(简体) )
    -   每个 `|`编号 :`+` 片段自行转换( n)`South Korea|Japan` → `KR|JP`); 其它任何东西(`null`, (中文(简体) ), `XK`, (中文(简体) ), `zh-cn`,则 `countries/DEU` 路径窗体)按给定发送
-   `select` 返回已校正的按实体类型默认值,除非覆盖,或 `["*"]` ; 无效的字段名称错误。 关于工作, `author_list` 返回作者顺序中的每个作者为 `{id, display_name, orcid}` - 大约十分之一大小 `authorships`,它增加了机构和从属关系——并且从来不是违约的一部分或 `["*"]`
-   关键词的光标和精确搜索,每页最多100个结果(默认为25个);语义搜索用 `page` (1个基数)相反,每页最多可有50个基数,同时将任意一个基数与错误相混合 `search_mode` 在上游呼叫前被拒绝
-   `sample` (最多10 000人)加确定型 `seed` 用于可复制的随机采样; 仅关键词和精确模式, 且绝不与 `sort` 或者说 `cursor` ——OpenAlex不采样语义搜索并拒绝排序样本,因此这些组合在上游调用前被否决. `per_page` 默认为 `min(sample, 100)`,因此一个100个或更少的样本在一个呼叫中完整返回;一个更大的一个被带 `page` (单位:千美元) `seed` (单位:千美元)`sample_page_without_seed` (无记录),最高记录为一万(`sample_page_too_deep` 通过它)
-   一个页面是 `per_page` 全部记录和记录 `id` 查找返回每个选定的整组阵列; `slice: {field, offset, limit}` 一个 `id` 逐个数组搜索一页( e)`limit` 默认50,被夹到5000). 任一表面的反应超过8,000,000字节(`structuredContent`,或 `content[]` 文本)失败为 `response_too_large` 名称a `per_page` 或者说 `slice.limit` 合适,或狭小 `select`
-   名单记录,有100张 `authorships` 或者说 `author_list` 条目标记为可能封顶,并带有 `id` + 键 `slice` 呼叫以获取更多存储的作者 。 Singleton的检索和快照保留了最多5 000份作品的作者;在该天花板上,每个片段都可能保留两个作者字段. `total` 计算存储的条目,而不是完整的下行,以及 `next` 当这些条目被耗尽时,就变得无效。 另一个 OpenAlex 抓取或快照无法回收超过存储上限的作者
-   超大小正整数夹住其盖子,要求/应用的尺寸在 `notice`一个日志和一个计数器: `per_page` 100以上(分析200人,语义搜索50人), `slice.limit` 5 000人以上,以及 `sample` 超过一万 设定 `OPENALEX_CLAMP_PER_PAGE=false` 以他们的头顶拒绝他们。 零,负数,分数总是拒绝. 一个 `id` 忽略页面大小
-   `display_name` 对无标题记录无效;每份呼叫报告 OpenAlex 每日预算费用和剩余余额

* * *

### `openalex_analyze_trends` 工具

-   将任何支持的字段分组,以便进行趋势、分布或比较分析 `filters` 范围,然后汇总
-   每页最多200组(默认). 没有光标, `order: "count"` (默认)通过计数返回上N,不再有页; `order: "key"` 以光标页标出不同的值。 布尔字段保持计数顺序, 即使使用 `"key"` ,不支持光标页。 提供 `cursor` 即使在 `order` 删除或 `"count"`。OpenAlex可以将按键顺序行走包到更早的分组:当页面的第一个按键重复更早的按键,或者当页面短或空时停止,即使 `next_cursor` 尚存
-   `include_unknown` (默认) `false`)为对分组字段没有值的实体添加一组,标记 `is_unknown: true` ,并在文本输出中标为未知。 当地人 `:include_unknown` 打开后缀 `group_by` 即使有明确的规定 `false`;通过两个后加后缀一次. OpenAlex 键它 `-111`编号 :`-111.0` (数字字段), `unknown` (文本字段和 `order: "key"`),或ID结束于 `/unknown`; 密钥是 sentinel, 不是过滤值 。 布尔字段没有这样的组——缺失值计为 `false`
-   `key_display_name` 仍然在场,但可以 `null` 当 OpenAlex 提供不标签时; 文本输出在此情况下使组合键, 包括未知的桶
-   并不是每个字段都是可组合的——生枣字段, `.search` 运营商, `from_*`编号 :`to_*` 区域修改器,小数分数,例如 `fwci`, (中文(简体) ), `display_name`,外部识别字段,例如 `doi`,而 OpenAlex 从一个相关实体中查找 `primary_location.source.country_code` 被拒绝; `openalex_describe_fields(entity_type, "group_by")` 列出该组合的字段
-   一个工作组 by on `authorships.countries` 在其通知中说 OpenAlex 仅计算每个作品对这个领域的前100名作者,以及姓名 `authorships.institutions.country_code` 作为全部的场
-   `entity_type: "awards"` 按字段划分,例如 `start_year`, (中文(简体) ), `funder.id`,或 `funding_type`; 组数奖而不和 `amount_usd`
-   OpenAlex 每日预算费用和剩余余额——汇总价格远低于向同一实体求助的价格

* * *

### `openalex_resolve_name` 工具

-   一个名称或部分名称运行对作品,作者,来源,机构,主题,关键词,出版商,以及资助者的自动完整搜索:最多10个匹配并带有分解提示(最后一个机构,主办组织,地点等)
-   获奖身份( Q)`G…`,光线或作为 OpenAlex URL)不发送请求: OpenAlex 没有自动完成授标,所以答复是空的,通知中指定了 `openalex_search_entities` 打电话打开奖项。 在明确 `entity_type`一个赤裸的 `G…` 搜索为该类型的名称
-   一个标识符 — OpenAlex ID, DOI, ORCID, ROR, PMID, ISSN, 或关键词 URL, 赤裸或以 URL 形式, 直接解决到它所处理的记录, 如它所属的实体类型. 一个ROR可以同时命名一个组织的机构,资助者和出版商的记录:没有 `entity_type` (或任何其他类型)所有三个被平行地检查,作为无票单子取出,发现的每张记录都被退回,机构优先; `entity_type` `institutions`, (中文(简体) ), `funders`,或 `publishers` 把它缩小到那个 Crossref 基金管理人登记册`10.13039/…`解决供资者,除非 `entity_type` 实值 `works`. PMCID 被承认,但解决不了任何问题 — OpenAlex Index no
-   短名共享赤裸的 OpenAlex ID 形状( 关键词) `p53` 读作出版商 `P53`),所以一个赤裸的OpenAlex ID,解决任何问题都将作为下一个名字被搜索,在 `entity_type` 当给出时,通知中标出两种结果;一个真实的ID仍然通过它的一个请求解决. 下 `entity_type: "keywords"` 形状从开始就作为关键字名查找
-   `filters` 缩小仅自动完成并需要 `entity_type` ——通过名称查询 `filters` 在任何请求之前均不予以拒绝`filters_without_entity_type`) (中文(简体) ). 在身份识别查询中,它们被忽略,在通知中被命名;名称搜索与任何信息都不匹配 `filters` 呼应他们,建议先放轻松
-   与 `entity_type` 设置, OpenAlex 自动完成在超过 1000 个字符的名称上失败;失败一次报告为 `query_too_long` 提出缩短姓名的建议,而不是作为停产重新考核
-   每日预算费用和剩余余额

* * *

### `openalex_get_citation_graph` 工具

-   `direction` 设置边缘 : `cites` (作品引用了种子), `cited_by` (种子本身的参考列表), `related_to` (OpenAlex的算法相关作品,~8-30典型,可能为空)
-   `seed_id` 接受 OpenAlex 工作 ID( 空白, 或其 OpenAlex 记录页或 API URL) 、 DOI, 或 PMID( PMCID 承认但解决不了任何问题 ) ; 先对一个活的搜索进行验证, 因此一个不存在的种子失败 `NotFound` 而不是返回空图表,而另一个实体类型的ID失败为 `id_type_mismatch` 在任何上游呼叫之前
-   堆叠与 `filters`编号 :`sort`编号 :`select` (单位:千美元)`author_list` 包括)缩小图; `filters` 无法设置 `cites`编号 :`cited_by`编号 :`related_to`,或其中一种的别名,例如: `cited_works` - 这些钥匙是留给 `direction`
-   Cursor pagining, 每页最多100个结果( 默认 25); 一个页面是 `per_page` 整个工作
-   同样的800万字节 `response_too_large` 失败( 命名为 a) `per_page` 和100名作者的上限披露 `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.id` 打开顶部 `G…` 身份证明 `entity_type: "awards"` 由于没有多少奖项包含自己的主题

## 特征

建造在 [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): stdio和可流式的 HTTP 传输器,可插接式(`none` 编号 : `jwt` 编号 : `oauth`),可互换存储(`in-memory`, (中文(简体) ), `filesystem`, (中文(简体) ), `Supabase`, (中文(简体) ), `Cloudflare KV/R2/D1`),结构化记录,可选择的OpenTeleometry tracking.

OpenAlex 特性 :

-   自动身份正常化的 API 客户端( DOI, ORCID, ROR, PMID, PMCID, ISSN, OpenAlex 记录页和 API URL) `http`, (中文(简体) ), `https`或没有计划, PubMed/ PubMed 中央 URLs ); PMCID 规范化,但自 OpenAlex 索引后, 解决不了任何问题
-   默认无密钥——可选的 API 密钥提高率和每日预算限制,以及可选的 `mailto` 识别 OpenAlex 的有礼貌的游泳池的呼叫者
-   HTTP 状态代码映射到特定的 MCP 错误类( 400 ~ 无效的Params, 或当语义搜索的查询嵌入在上游失败时无法使用 ; 422 → 验证错误; 429 → 速率限制, 或当429 拒绝付费计划过滤器时禁止) , 上游信息浮出水面
-   超时提醒请求重试和取消支持 `AbortSignal`

方便代理输出 :

-   证明——每个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 实体根据完整的 WHWG 表解码, 注释和 HTML/JATS/ MathML 格式化标记被去除, CDATA 包装和 IOP `<?CDATA …?>` 数学标记被解开 `% MathType!MTEF!…!44A1!`)在重复它们的TeX 保留时被去除,并出现双向脱逃的换行符(一字节) `\n`)成为空格;文字文本,例如 `A < B`, (中文(简体) ), `95% CI`,例如 TeX `\nu` 保留。 标识符和 URL 字段(`id`, (中文(简体) ), `doi`, (中文(简体) ), `ids`, (中文(简体) ), `orcid`, (中文(简体) ), `ror`, (中文(简体) ), `issn`, (中文(简体) ), `*_url`, 线程) 的返回恰好与 OpenAlex 存储它们一样, 所以每一个在返回时都会解决。 文本输出为 Markdown 从文本中逃出, 所以一个偏差 `*`, (中文(简体) ), `<tag>`,或 `[x](y)` 使换行符、分页符、引导或后移空格在结构化输出时读回; 多行 `display_name` 自行制作 `**Display Name:**` 线条。 通知员以同样的方式逃出呼叫器文本. 作为链接的 ID 和 URL 保持字节相同

## 开始

连接到主机实例, 没有安装 :

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

或者在当地运行它:

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

对于其他客户端,请将此添加到 MCP 配置文件中 :

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

可选 `OPENALEX_API_KEY` 免费的 [OpenAlex 账户密钥](https://openalex.org/settings/api) 提高费率限制和日常预算,而不是匿名; `OPENALEX_MAILTO` 将您识别为 OpenAlex 的 [礼貌的游泳池](https://developers.openalex.org/guides/authentication)。对于 Docker 或源构建,参见 [运行服务器](https://npmcn.com/package/%40cyanheads/openalex-mcp-server/#readme-running-the-server)。 。 。 .

## 配置

| 变量 | 说明 | 默认 |
| :-- | :-- | :-- |
| `MCP_TRANSPORT_TYPE` | 运输: `stdio` 或者说 `http`。 。 。 . | `stdio` |
| `MCP_HTTP_PORT` | HTTP 服务器端口 . | `3010` |
| `MCP_SESSION_MODE` | HTTP 会话模式 : `stateless`, (中文(简体) ), `stateful`,或 `auto` (解决办法是: `stateful`) (中文(简体) ). 服务器声明 `stateless` 在代码中;一个明确的值将覆盖它. | `stateless` |
| `MCP_AUTH_MODE` | Auth 模式 : `none`, (中文(简体) ), `jwt`,或 `oauth`。 。 。 . | `none` |
| `MCP_ALLOWED_ORIGINS` | 以逗号分隔的浏览器允许列表 `Origin` hTTP 传输头. 取消设置 = 仅循环;设置为 `*` 以禁用. | _只循环_ |
| `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/sets/api (英语)](https://openalex.org/settings/api)) (中文(简体) ). 没有它,则适用匿名费率限制. | —— 说 |
| `OPENALEX_MAILTO` | 向上游发送电子邮件 `mailto=` 来识别自己到 OpenAlex("polyte pool"); 一个礼貌标识符,与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个检索/引用、50个语义、200个分析), `slice.limit` (5 000美元),以及 `sample` (10 000) 附有请求/适用通知。 设定 `false` 以拒绝每个在其封顶上;无效的布尔值失败启动. | `true` |
| `OTEL_ENABLED` | 启用 [OpenTelemet 仪器](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) (日文、度量、完成日志). | `false` |

见 [`.env.example`](https://npmcn.com/package/%40cyanheads/openalex-mcp-server/.env.example) 用于完整可选覆盖列表.

## 运行服务器

### 地方发展

要求数 [Bun v1.4.0 (英语)](https://bun.sh/) 或更高(或Node.js v24+).

-   **克隆并安装 :**
    
    ```sh
    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
    ```
    
-   **构建和运行 :**
    
    ```sh
    # One-time build
    bun run rebuild
    
    # Run the built server
    bun run start:stdio
    # or
    bun run start:http
    ```
    
-   **运行检查和测试 :**
    
    ```sh
    bun run devcheck   # Lints, formats, type-checks
    bun run test       # Runs the test suite
    ```
    

### 夹克

```sh
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 .`; OpenTeleometry 端点依赖性默认安装——用 `--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客户端,字段目录,和域类型. |
| `skills/` | 发表 `openalex-guide` 代理技能,在MCP上服务,并随包裹一起发运. |
| `tests/` | 单位和综合测试,反映 `src/` 结构. |

## 发展指南

见 [`CLAUDE.md`](https://npmcn.com/package/%40cyanheads/openalex-mcp-server/CLAUDE.md) 发展准则和建筑规则。 简本:

-   搬运工投掷,框架渔获量——否 `try/catch` 在工具逻辑中
-   使用 `ctx.log` 用于伐木, `ctx.state` 用于存储
-   环绕 OpenAlex 响应: 验证原始有效载荷 正常到域类型 返回输出计划; 永远不编织缺失的字段
-   总是通过 `openalex_resolve_name` 按实体过滤前

## 捐款

问题值得欢迎。 提交前运行检查 :

```sh
bun run devcheck
bun run test
```

## 许可证

阿帕奇-2.0 — 见 [自由主义](https://npmcn.com/package/%40cyanheads/openalex-mcp-server/LICENSE) 详细情况.

## 常见问题

### @cyanheads/openalex-mcp-server 是什么？

通过MCP访问OpenAlex学术研究目录——270M\+出版物\. \(原始内容存档于2012-10-12\)\. STIO or Streamable HTTP\.

### 如何安装 @cyanheads/openalex-mcp-server？

在项目目录运行 npm install @cyanheads/openalex-mcp-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 openalex-mcp-server，可以用 npx openalex-mcp-server 直接运行。

### @cyanheads/openalex-mcp-server 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cyanheads/openalex-mcp-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cyanheads/openalex-mcp-server 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cyanheads/openalex-mcp-server 可以商用吗？

@cyanheads/openalex-mcp-server 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cyanheads/openalex-mcp-server 的下载量有多少？

根据 npm 官方下载统计，@cyanheads/openalex-mcp-server 在 2026/10/11 – 2026/11/09 这 30 天内被下载 4,020 次，日均约 134 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cyanheads/openalex-mcp-server 还在维护吗？

最新版本 0\.11\.0 发布于 2026/10/29（13 天前）；至今共发布 53 个版本，其中过去 12 个月发布了 53 个；首次发布于 2026/03/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。