Content
# openalex-mcp
[Polski](README.pl.md)
OpenAlex scholarly metadata API MCP server.
## Table of contents
- [Tools](#tools)
- [Environment variables](#environment-variables)
- [Wiring it up](#wiring-it-up)
- [Local run](#local-run)
## Tools
### Primary scholarly entities (specific tools)
| Tool | Parameters | Description |
|------|-----------|------|
| `search_works` | `search?, filter_?, sort?, search_filter?, group_by?, select?, per_page?, pagination?, include_xpac?` | Search / filter / aggregate works. Default `select` returns compact fields. |
| `get_work` | `work_id, select?` | Single work by `W123` / `doi:...` / `pmid:...` |
| `search_authors` | `search?, filter_?, sort?, search_filter?, group_by?, select?, per_page?, pagination?` | Search authors |
| `get_author` | `author_id, select?` | Author by `A123` / `orcid:...` |
| `search_sources` | `search?, filter_?, sort?, search_filter?, group_by?, select?, per_page?, pagination?` | Journals / repositories |
| `get_source` | `source_id, select?` | Source by `S123` / `issn:...` |
| `search_institutions` | `search?, filter_?, sort?, search_filter?, group_by?, select?, per_page?, pagination?` | Institutions |
| `get_institution` | `institution_id, select?` | Institution by `I123` / `ror:...` |
| `search_topics` | `search?, filter_?, sort?, group_by?, select?, per_page?, pagination?` | Research topics |
| `get_topic` | `topic_id, select?` | Topic by `T123` |
### Secondary & dictionary entities (generic tools)
| Tool | Parameters | Description |
|------|-----------|------|
| `list_entities` | `entity: enum, search?, filter_?, sort?, group_by?, select?, per_page?, pagination?` | List secondary or dictionary entities |
| `get_entity` | `entity: enum, entity_id, select?` | Fetch secondary or dictionary entity by ID |
`entity` accepts one of: `publishers`, `funders`, `awards`, `keywords`, `concepts`, `domains`, `fields`, `subfields`, `sdgs`, `countries`, `continents`, `languages`, `work-types`, `source-types`, `institution-types`, `licenses`.
### Special endpoints
| Tool | Parameters | Description |
|------|-----------|------|
| `autocomplete` | `entity_type: enum, query` | Fast typeahead. `entity_type` accepts: works, authors, sources, institutions, topics, publishers, funders, concepts |
| `get_abstract` | `work_id` | Reconstruct abstract text from `abstract_inverted_index`. Compact (~1-3KB). |
| `get_fulltext_url` | `work_id` | Return all PDF / OA URLs for a work. Compact. |
| `get_fulltext` | `work_id, max_chars=8000` | **Heavy.** Download PDF, extract text. Use only when user explicitly asks for fulltext. |
| `raw_request` | `method, path, params?, body?` | Raw pass-through for advanced queries |
### Default `select`
To keep responses compact, `search_works` / `search_authors` / `search_sources` / `search_institutions` / `search_topics` apply a default `select` field set when `select` is not provided. Pass `select` explicitly to override, or `select="*"` to disable the default and receive full objects (verbose).
### `pagination` format
Single string parameter replacing `page` / `cursor` / `sample` / `sample_seed`:
| Form | Behavior |
|------|----------|
| `None` | First page (basic pagination) |
| `"N"` or `"page:N"` | Page N (1-500) |
| `"cursor:*"` | Start cursor pagination (deep pagination past 10 000 results) |
| `"cursor:VALUE"` | Continue cursor with token from `meta.next_cursor` |
| `"sample:N"` | Random sample of N (max 10 000) |
| `"sample:N:seed:S"` | Reproducible random sample |
### OpenAlex parameter cheat sheet
- `search` — full-text search (Boolean AND/OR/NOT, `"phrase"`, `term~1` fuzzy, wildcards `*`/`?`).
- `filter_` — e.g. `publication_year:2020-2024,is_oa:true,cited_by_count:>10`. Operators: `:`, `!`, `>`, `<`, `|` (OR), `&`/`,` (AND), `null`, `has:`.
- `sort` — e.g. `cited_by_count:desc,publication_date:desc`.
- `group_by` — e.g. `publication_year` or `primary_topic.id`.
- `search_filter` — e.g. `title.search:"machine learning"`.
Full docs: https://docs.openalex.org
## Environment variables
| Variable | Required | Description |
|---------|----------|------|
| `OPENALEX_MCP_EMAIL` | no | Email for the polite pool (faster rate limits; passed as `mailto`) |
## Wiring it up
Only requirement: `uv` (https://docs.astral.sh/uv/). Nothing else to install.
### Claude Code
```
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 Desktop / other MCP client
```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" }
}
}
}
```
After pushing a new version: `uv cache clean` and restart the client.
## Local run
```
uv run --directory . openalex-mcp
```
Tests (manual):
```
uv run --directory . --with pytest pytest test/
```
