openalex-mcp-server

Public Hosted Server:https://openalex.caseyjhand.com/mcp

Five tools for querying theOpenAlexacademic research catalog:

- Retrieve a single entity by ID (OpenAlex ID, DOI, ORCID, ROR, PMID, PMCID, ISSN).idtakes precedence: search criteria passed alongside it are not applied, and the response says which ones were dropped rather than echoing them back as though they ran. The search-only validations (semantic page cap,samplewithcursor,seedwithoutsample) are skipped too — a lookup is never rejected over parameters it ignores
- Keyword search with boolean operators, quoted phrases, wildcards, and fuzzy matching
- Exact and AI semantic search modes
- Rich filter syntax: AND across fields, OR within fields (us|gb), NOT (!us), ranges (2020-2024), comparisons (>100)
- Sensible default field selection per entity type, applied to both searches and ID lookups — prevents oversized responses; passselectto choose fields, or[""]for the full record
- Invalidselectfield names produce an error listing the valid fields for that entity type
- Formatted MCP output is a generic markdown renderer — every returned field is surfaced without per-entity-type hard-coding
- Cursor pagination and up to 100 results per page;sorttakes a single key or a comma-separated list, with the-descending prefix applied per key
- display_nameis nullable — OpenAlex holds no title for paratext and other untitled records, which pass through instead of failing the whole page

- List valid fields for any entity type and context (filter,group_by, orselect)
- group_byreturns the subset of thefilterset OpenAlex can aggregate — raw date fields,.searchoperators, andfrom_/to_range modifiers are excluded
- Passquery(a partial or guessed name) to rank results by name similarity — surfaces the right field when you only know roughly what you want
- Complements the ranked "did you mean" suggestions now appended to invalid-field errors on the search, trends, and citation-graph tools

- Declarative tool definitions — single file per tool, framework handles registration and validation
- Unified error handling across all tools
- Pluggable auth (none,jwt,oauth)
- Swappable storage backends via the framework (not currently used by this server)
- Structured logging with optional OpenTelemetry tracing
- Runs locally (stdio/HTTP) or in Docker from the same codebase

- Typed API client with automatic ID normalization (DOI, ORCID, ROR, PMID, PMCID, ISSN, OpenAlex URLs)
- Abstract reconstruction from inverted indices — plaintext instead of OpenAlex's position-keyed encoding
- HTTP status codes mapped to specific MCP error classes (400 → InvalidParams, 422 → ValidationError, 429 → RateLimited, etc.) with upstream messages surfaced
- Every API-calling tool reports what the call spent against the OpenAlex daily budget and what is left of it, so a paginated sweep can be priced before it runs instead of ending in a 429. An account holding prepaid balance sees that too, since it keeps serving once the day's allowance is gone
- Timeout-aware request retries and cancellation support viaAbortSignal

A public instance is available athttps://openalex.caseyjhand.com/mcp— no installation required. Point any MCP client at it via Streamable HTTP:

{ "mcpServers": { "openalex-mcp-server": { "type": "streamable-http", "url": "https://openalex.caseyjhand.com/mcp" } } }

Add to your MCP client config (e.g.,claude_desktop_config.json):

{ "mcpServers": { "openalex-mcp-server": { "type": "stdio", "command": "npx", "args": ["-y", "@cyanheads/openalex-mcp-server"], "env": { "OPENALEX_API_KEY": "your-openalex-api-key" } } } }

OPENALEX_API_KEYis optional — set it to a freeOpenAlex account keyfor keyed rate limits and budget under OpenAlex's usage-based pricing, or omit it for anonymous access. SetOPENALEX_MAILTOto an email if you want to identify yourself to OpenAlex (thepolite pool).

git clone https://github.com/cyanheads/openalex-mcp-server.git

bun run build bun run start:http # or start:stdio

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

docker build -t openalex-mcp-server . docker run -e OPENALEX_API_KEY=your-key -p 3010:3010 openalex-mcp-server

SeeCLAUDE.mdfor development guidelines and architectural rules. The short version:

An MCP (Model Context Protocol) server for searching and analyzing academic papers across multiple databases (Semantic Scholar, Crossref, OpenAlex, PubMed), with regex-powered filtering and statistical analysis.