内容
OpenAlex MCP
一款用于学术搜索、论文、引用图、作者和场地解析、候选收获、API 配额可见性 OpenAlex 进行受保护的全文本下载的独立 [模型上下文协议（MCP）](https://modelcontextprotocol.io/) 服务器。
它使用带有 stdio 传输的官方 Python MCP SDK，并与任何可以启动本地命令的 MCP 客户端配合服务器独立于任何笔记应用程序或代理工作流。
> 本项目是一个社区项目，与 OpenAlex 无关。元数据和全文内容仍受 OpenAlex 和原始出版商的条款约束。
## 功能
| 工具 | 用途 |
|---|---|
| `search_works` | 搜索标题和摘要或带有日期、场地、作者、主题、OA、arXiv、引用、排序和分页过滤器 |
| `get_work` | 通过 OpenAlex W-id、DOI、arXiv ID/URL 或确切标题解析一篇论文，并返回详细的元数据 |
| `get_citing_works` | 查找引用某篇论文的后续作品 |
| `get_references` | 丰富论文的参考文献，并按引用计数排名 |
| `search_authors` | 按姓名或 ORCID 查找作者 |
| `resolve_entity` | 通过名称、ISSN 或 OpenAlex ID 解析来源、主题和机构 |
| `harvest_candidates` | 运行最近、补全、主题、场地、引用、作者和慢窗口检索，然后排除、重复数据删除并与 RRF 合并结果 |
| `get_api_quota` | 显示官方 `/rate-limit` 预算、剩余配额、重置时间和端点价格 |
| `download_work_pdf` | 下载 OpenAlex 托管的 PDF 或 GROBID XML，带有根边界、大小、魔术字节和原子写入检查 |
当前工具响应为中文，而论文标题和技术术语仍保留其原始语言。
## 前置条件
您需要：
- Python 3.12 或更新版本
- [uv](https://docs.astral.sh/uv/)
- OpenAlex API 密钥
- 支持本地 stdio 服务器的 MCP 客户端
使用大多数 uv 工作流时，您不需要单独安装 Python：uv 可以为项目安装和管理兼容的 Python 解释器。
## 1. 安装 uv
使用以下官方安装方法之一。
### macOS 和 Linux
```bash
curl -LsSf httpsal.sh/uv/install.sh | sh
```
Homebrew 也支持：
```bash
brew install uv
```
### Windows
在 PowerShell 中```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/install.ps1 |"
```
或使用 Win
```powershell
wing --id=astral-sh.uv -e
```
如果安装程序更新了您的 `PATH`，请重启终端，然后验证安装：
```bash
uv --version
uv python install 3.12
```
参见官方 [uv 安装指南](https://docs.astral.sh/uv/getting-started/installation/) 以获取其他包管理器和卸载说明。
## 2. 获取 OpenAlex API 密钥
1. 打开 <https://openalex.org/settings/api>。
2. 登录或创建 OpenAlex 账户。
3. 在 API 设置页面创建或显示您的 API 密钥。
4. 将密钥保存在密码管理器中，直到您将其添加到本地 MCP 客户端配置中。
服务器仅从 `OPENALEX_API_KEY` 读取密钥。永远不要提交密钥、将其粘贴到问题中或在日志中放置包含 `api_key=...` 的 URL。OpenAlex 配额和价格可能会发生变化；请在设置完成后使用 `get_api_quota` 查看您账户的当前值。
## 3. 选择安装方法
### 选项 A：使用 uvx 直接从 GitHub 运行
这是最简短的安装方式：
```bash
uvx --from git+https://github.com/DeyangLiu123/openalex-mcp.git openalex-mcp
```
`uvx` 创建了一个隔离环境并运行命令。对于可复制的部署，请将 Git URL 固定到提交：
```bash
uvx --from git+https://github.com/DeyangLiu123/openalex-mcp.git@<commit-shaalex-mcp
```
在终端中启动命令时，它似乎正在等待，因为它是一个 stdio MCP 服务器。通常，您的 MCP 客户端会启动它并通过 stdin/stdout 进行通信。
### 选项 B：安装持久的用户级命令
```bash
uv tool install git+https://github.com/DeyangLiu123/openalex-mcp.git
openalex-mcp
```
验证可执行文件安装位置：
```bash
uv tool list
```
更新 VCS 安装时：
```bash
uv tool install --force git+https://github.com/DeyangLiu123/openalex-mcp.git
```
### 选项 C：克隆用于开发或审计
```bash
git clone https://github.com/DeyangLiu123/openalex-mcp.git
cd openalex-mcp
uv sync --locked
uv run pytest -m "not live"
```
本地可执行文件位于：
```text
.venv/bin/openalex-mcp # macOS/Linux
.venv\Scripts\openalex-mcp.exe # Windows
```
## 4. 配置 MCP 客户端
### 通用 stdio 配置
许多桌面和编辑器客户端接受以下 JSON 配置：
```json
{
"mcpServers": {
"openalex": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/DeyangLiu123/openalex-mcp.git",
"openalex-mcp"
],
"env": {
"OPENALEX_API_KEY": "your-api-key"
}
}
}
}
```
确切的配置文件名和位置取决于客户端。请保持此文件本地且不进行版本控制，因为它包含 API 密钥。
对于克隆安装，请将 `command` 替换为 macOS/Linux 上的 `.venv/bin/openalex-mcp` 或 Windows 上的 `.venv\\Scripts\\openalex-mcp.exe` 的绝对路径，并将 `args` 设置为空数组。
### Codex
Codex CLI、Codex IDE 扩展和 Codex 桌面体验在 `~/.codex/config.toml` 中共享相同的 MCP 配置。使用 Codex CLI 注册服务器：
```bash
codex mcp add openalex \
--env OPENALEX_API_KEY=<your-api-key> \
-- uvx --from git+https://github.com/DeyangLiu123/openalex-mcp.git openalex-mcp
```
验证注册：
```bash
codex mcp list
codex mcp get openalex
```
在更改 MCP 配置后，请重启 Codex 或打开新会话。在交互式 Codex 会话中，使用 `/mcp` 确认 `openalex` 已连接及其九个工具可见。
等效的 `~/.codex/config.toml` 条目是：
```toml
[mcp_servers.openalex]
command = "uvx"
args = [
"--from",
"git+https://githubeyangLiu123/openalex-mcp.git",
"openalex-mcp",
]
env = { OPENALEX_API_KEY = "your-api-key" }
```
保持 `~/.codex/config.toml` 私有，因为此表单在本地存储密钥。如果您在 Codex 配置之外管理机密，请将 ` 行替换为 `env_vars = ["OPENAL_KEY"]`，确保在启动 Codex 的环境中存在该变量，并重启 Codex。
有关更多详细信息，请参阅官方 [Codex MCP 文档](https://learn.chatgpt.com/docs/extend/mcp)。
### Claude Code
使用 `uvx` 安装方法：
```bash
claude mcp add --scope user openalex \
-e OPENALEX_API_KEY=<your-api-key> \
-- uvx --from git+https://github.com/DeyangLiu123/openalex-mcp.git openalex-mcp
```
然后验证 Claude Code 是否看到服务器：
```bash
claude mcp list
```
如果您不希望字面密钥出现在 shell 历史记录中，请先将其读入临时环境变量，然后在注册命令中使用该变量：
```bash
read -s OPENALEX_API_KEY
export OPENALEX_API_KEY
claude mcp add --scope user openalex \
-e OPENALEX_API_KEY="$OPENALEX_API_KEY" \
-- uvx --from git+https://github.com/DeyangLiu123/openalex-mcp.git openalex-mcp
unset OPENALEX_API_KEY
```
## 基于提示的 Codex 或 Claude Code 部署
现代编码代理可以检查存储库、安装包、配置其自己的 MCP 客户端并验证结果。将以下内容复制到 Codex 或 Claude Code 中。
```text
请为我://github.com/DeyangLiu123/openalex.git 安装 OpenAlex MCP 服务器。
要求：
1进行更改之前检查 README 和 pyproject.toml。
2. 检查是否已 和 uv。如果缺少在运行网络安装说明适用于您的操作安装命令并询问. 使用 Python 3.12 或更新版本。优先使用 `uvx --from git+https://github.com/DeyangLiu123/opencp.git openalex-mcp`；仅当您的 MCP 客户端需要绝对可执行文件路径时才使用本地克隆。
4. 如果克隆存储库，请运行离线测试套件。未经我许可，请勿运行实时测试或付费下载测试。
5. 仅当您准备好配置 MCP 服务器时，请向我询问 OPENALEX_API_KEY。仅在您的本地 MCP 客户端环境配置中存储它。永远不要将其写入存储库、跟踪文件、聊天响应或日志中。
6. 使用用户范围的 stdio MCP 服务器配置当前 Codex 或 Claude Code 安装，名为 `openalex`。
7. 除非我明确选择加入文件下载，否则请保持 OPENALEX_DOWNLOAD_ROOT 未设置。如果我选择加入，请将其设置为我批准的绝对目录。
8. 验证 MCP 服务器已注册及其九个工具可见。然后调用 get_api_quota 并执行一个低成本的搜索以获取三个 KV 缓存论文。
9. 报告已安装的命令、配置位置、验证结果以及可能产生的任何 API 成本。不要创建 GitHub 发布或修改 OpenAlex MCP 源存储库。
```
在批准代理的提议命令之前，请审查它们，尤其是网络安装程序、客户端配置更改以及包含凭证的任何命令。
## 5. 验证设置
在注册后启动新的 MCP 客户端会话并尝试：
```text
使用 OpenAlex 查找三篇关于 KV 缓存的论文。然后显示引用最多的结果的关键参考文献。
```
您还可以要求客户端调用 `get_api_quota`。成功的结果应显示每日预算、使用情况、剩余配额、重置时间、当前端点价格以及该 MCP 服务器进程累计的成本。
## 配置参考
| 环境变量 | 默认值 | 描述 |
|---|---|---|
| `OPENALEX_API_KEY` | 未设置 | 必需。服务器可以在没有它的情况下启动，但工具会返回设置指南 |
| `OPENALEX_BASE_URL` | `https://api.openalex.org` | OpenAlex API 基本 URL |
| `OPENALEX_CONTENT_BASE_URL` | `https://content.openalex.org` | OpenAlex 内容 API 基本 URL |
| `OPENALEX_TIMEOUT` | `30` | HTTP 超时，单位：秒 |
| `OPENALEX_DOWNLOAD_ROOT` | 未设置 | 文件下载被禁用，直到配置了此绝对根目录 |
| `OPENALEX_MAX_DOWNLOAD_BYTES` | `209715200` | 最大下载文件大小，默认 200 MiB |
要启用内容下载，请在 MCP 进程环境中添加批准的绝对目录：
```json
{
"OPENALEX_API_KEY": "your-api-key",
"OPENALEX_DOWNLOAD_ROOT": "/absolute/path/to/papers"
}
```
`download_work_pdf` 工具可能只会写入此根目录或其子目录。
## 使用说明
### 作品搜索
`search_works` 默认使用更精确的标题和摘要搜索，并支持：
- `from_date` / `to_date`，或出版 `year`
- `venue_ids`、`author_ids` 和 `topic_ids`
- `oa_only`、`arxiv_only` 和 `min_citations`
- `sort=relevance|date|citations`
- 分页或游标分页
OpenAlex 通常为每个会议年份创建一个单独的来源记录。要检查一个版本，首先调用 `resolve_entity(entity_type="source", query="INFOCOM 2026")`，验证规范名称和年份，然后将得到的来源 ID 传递给 `search_works(venue_ids=[...])`。优先使用 ISSN 解析期刊。
### 标识符和歧义
- OpenAlex W-ids 和 URL 直接解析。
- DOI 和 arXiv 输入使用单一查找。缺少的标识符被报告为未编制索引，而不是被静默替换为模糊文本搜索。
- 仅当其规范化表单完全匹配时，才自动接受标题。否则，服务器返回最多三个候选项供调用者选择。
- 列表首先按规范化 DOI 然后按规范化标题进行重复数据删除。
### 候选收获
`harvest_candidates` 旨在用于文献警报和推荐工作流。基本查询使用 `{"line": "label", "q": "query"}` 对象，可以与临时主题、场地 ID、引用种子、作者和 JSONL 排除文件结合使用。
输出报告路由计数、每个查询的覆盖率、适应性回填页面、排除、重复数据删除、RRF 分数和 API 成本。免费 OpenAlex 计划不公开 `from_created_date`，因此默认策略将最近窗口与较旧的出版日期回填相结合。它减少了延迟索引造成的损失，但不能保证在配置的窗口或最大页面数之外进行检索。
## API 成本和速率限制
使用 `get_api_quota` 作为运行时真相来源。OpenAlex 配额和端点价格可能会发生变化。典型的当前价格是：
- 单例查找：免费
- 仅过滤器列表请求：约 `$0.0001`
- 搜索请求：约 `$0.001`
- OpenAlex 内容下载：约 `$0.01`
每个工具报告调用的成本和当前 MCP 进程累计的成本。如果目标文件已经存在且 `overwrite=false`，则在计费内容请求之前会检测到它。
客户端区分无效凭证、付费计划限制、每日配额耗尽和短期速率限制。它重试有界的网络/服务器故障和短 `Retry-After` 响应。当 OpenAlex API 要求时，它还会序列化不常见的广泛布尔搜索。
## 下载安全边界
`download_work_pdf` 在显式配置 `OPENALEX_DOWNLOAD_ROOT` 之前无法写入文件。启用后：
- `dest_dir` 必须解析为配置的根目录或其子目录。
- `filename` 必须是basename；绝对路径、`..`、斜杠、反斜杠和 NUL 被拒绝。
- `Content-Length` 和实际流字节数都被限制。
- PDF 内容必须以 `%PDF` 开头；XML 必须具有 XML 声明或 `<TEI` 根。
- 随机临时文件被验证，然后原子化安装。
- 失败仅删除临时文件，不覆盖现有目标。
- 包含 API 密钥的 URL 从日志和错误中被删除。
## 测试
离线测试不访问网络：
```bash
uv run pytest -m "not live"
```
实时烟雾测试会发出低成本的 OpenAlex 请求：
```bash
OPENALEX_API_KEY=... uv run pytest -m "live and not paid"
```
免费计划金丝雀是可选的，因为它故意检查高级筛选器被拒绝：
```bash
OPENALEX_API_KEY=... OPENALEX_EXPECT_FREE_PLAN=1 \
uv run pytest tests/test_live.py::test_created_date_filter_remains_plan_gated
```
内容下载烟雾测试会产生额外费用，需要第二个明确选择：
```bash
OPENALEX_API_KEY=... OPENALEX_RUN_PAID_TESTS=1 \
uv run pytest -m "live and paid"
```
实时测试监控 API 语法、配额有效载体、标题和摘要兼容性、布尔查询、收获和可选内容下载。网络 API 行为和数据可能会发生变化，因此这些金丝雀需要持续维护。
## 故障排除
### `uv` 或 `uvx` 未找到
安装后重启终端并运行 `uv --version`。如果仍然缺少，请遵循 uv 安装程序打印的 PATH 说明或咨询上述官方安装指南。
### 服务器启动但无输出
对于等待客户端的 stdio MCP 服务器，这是正常的。请通过 MCP 客户端的服务器列表验证它，而不是交互式运行。
### 工具报告缺少 API 密钥
在 MCP 服务器条目的环境中设置 `OPENALEX_API_KEY`，而不是仅在无关的终端会话中设置。在更改 MCP 客户端配置后，请重启 MCP 客户端。
### HTTP 401、403 或 429
- `401`：密钥丢失或无效。
- `403` 或与计划相关的消息：请求的特性需要更高的 OpenAlex 计划。
- 其他 `：每日配额已用完或达到请求速率限制。请检查 `get_api_quota` 和 `Retry-After`。
### 下载被拒绝
设置 `OPENALEX_DOWNLOAD_ROOT` 为绝对目录，并保持 `dest_dir` 在其中。下载在变量缺失时保持禁用。
## 已知兼容性说明
OpenAlex 已弃用 `filter=field.search:` 但目前没有等效的非弃用仅标题和摘要查询。该项目在 `text_search_filter()` 中隔离当前行为，并使用实时金丝雀进行监控，以便将来的迁移仅限于一个兼容层。
## 贡献和安全
参见 [CONTRIBUTING.md](CONTRIBUTING.md) 获取开发要求，参见 [SECURITY.md](SECURITY.md) 获取漏洞报告。
## 许可证
[MIT](LICENSE)
