内容
# OpenAlex 元数据 API 中转服务器
## 目录
- [工具列表](#工具列表)
- [环境变量](#环境变量)
- [连接配置](#连接配置)
- [本地运行](#本地运行)
## 工具列表
### 主要学术实体（特定工具）
| 工具 | 参数 | 描述 |
|------|-----------|------|
| `search_works` | `search?, filter_?, sort?, search_filter?, group_by?, select?, per_page?, pagination?, include_xpac?` | 搜索/筛选/聚合作品。默认 `select` 返回精简字段。 |
| `get_work` | `work_id, select?` | 通过 `W123` / `doi:...` / `pmid:...` 获取单个作品 |
| `search_authors` | `search?, filter_?, sort?, search_filter?, group_by?, select?, per_page?, pagination?` | 搜索作者 |
| `get_author` | `author_id, select?` | 通过 `A123` / `orcid:...` 获取作者 |
| `search_sources` | `search?, filter_?, sort?, search_filter?, group_by?, select?, per_page?, pagination?` | 期刊/仓库 |
| `get_source` | `source_id, select?` | 通过 `S123` / `issn:...` 获取来源 |
| `search_institutions` | `search?, filter_?, sort?, search_filter?, group_by?, select?, per_page?, pagination?` | 机构 |
| `get_institution` | `institution_id, select?` | 通过 `I123` / `ror:...` 获取机构 |
| `search_topics` | `search?, filter_?, sort?, group_by?, select?, per_page?, pagination?` | 研究主题 |
| `get_topic` | `topic_id, select?` | 通过 `T123` 获取主题 |
### 次要和字典实体（通用工具）
| 工具 | 参数 | 描述 |
|------|-----------|------|
| `list_entities` | `entity: enum, search?, filter_?, sort?, group_by?, select?, per_page?, pagination?` | 列出次要或字典实体 |
| `get_entity` | `entity: enum, entity_id, select?` | 通过 ID 获取次要或字典实体 |
`entity` 支持以下取值：`publishers`, `funders`, `awards`, `keywords`, `concepts`, `domains`, `fields`, `subfields`, `sdgs`, `countries`, `continents`, `languages`, `work-types`, `source-types`, `institution-types`, `licenses`.
### 特殊端点
| 工具 | 参数 | 描述 |
|------|-----------|------|
| `autocomplete` | `entity_type: enum, query` | 快速输入提示。`entity_type` 支持：works, authors, sources, institutions, topics, publishers, funders, concepts |
| `get_abstract` | `work_id` | 从 `abstract_inverted_index` 重建摘要文本。精简 (~1-3KB)。 |
| `get_fulltext_url` | `work_id` | 返回作品的所有 PDF / OA URL。精简。 |
| `get_fulltext` | `work_id, max_chars=8000` | **繁重**。下载 PDF，提取文本。仅在用户明确要求全文时使用。 |
| `raw_request` | `method, path, params?, body?` | 用于高级查询的原始直通 |
### 默认 `select`
为了保持响应精简，`search_works` / `search_authors` / `search_sources` / `search_institutions` / `search_topics` 在未提供 `select` 时应用默认 `select` 字段集。显式传递 `select` 以覆盖，或使用 `select="*"` 以禁用默认设置并接收完整对象（详细）。
### `pagination` 格式
单个字符串参数替换 `page` / `cursor` / `sample` / `sample_seed`：
| 格式 | 行为 |
|------|----------|
| `None` | 第一页（基本分页） |
| `"N"` 或 `"page:N"` | 第 N 页（1-500） |
| `"cursor:*"` | 开始光标分页（深入分页超过 10,000 个结果） |
| `"cursor:VALUE"` | 使用 `meta.next_cursor` 中的令牌继续光标 |
| `"sample:N"` | 随机样本 N（最多 10,000） |
| `"sample:N:seed:S"` | 可重复的随机样本 |
### OpenAlex 参数速查表
- `search` — 全文搜索（布尔 AND/OR/NOT，`"phrase"`，`term~1` 模糊，通配符 `*`/`?`）。
- `filter_` — 例如 `publication_year:2020-2024,is_oa:true,cited_by_count:>10`。运算符：`:`，`!`，`>`，`<`，`|` （OR），`&`/`,` （AND），`null`，`has:`。
- `sort` — 例如 `cited_by_count:desc,publication_date:desc`。
- `group_by` — 例如 `publication_year` 或 `primary_topic.id`。
- `search_filter` — 例如 `title.search:"machine learning"`。
完整文档：https://docs.openalex.org
## 环境变量
| 变量 | 是否必需 | 描述 |
|---------|----------|------|
| `OPENALEX_MCP_EMAIL` | 否 | 礼貌池的电子邮件（更快的速率限制；作为 `mailto` 传递） |
## 连接配置
唯一要求：`uv`（https://docs.astral.sh/uv/）。无需安装其他依赖。
### Claude 代码
```
claude mcp add openalex-mcp -e OPENALEX_MCP_EMAIL=your@email.example -- uvx --from git+https://github.com/dam2452/openalex-mcp.git openalex-mcp
```
### Claude 桌面版 / 其他 MCP 客户端
```json
{
"mcpServers": {
"openalex-mcp": {
"command": "uvx",
"args": ["--from", "git+https://github.com/dam2452/openalex-mcp.git", "openalex-mcp"],
"env": { "OPENALEX_MCP_EMAIL": "your@email.example" }
}
}
}
```
推送新版本后：`uv cache clean` 并重启客户端。
## 本地运行
```
uv run --directory . openalex-mcp
```
测试（手动）：
```
uv run --directory . --with pytest pytest test/
```
