openalex-mcp-server — Claude Code MCP server: OpenAlex in your agent
Puts the OpenAlex catalog a prompt away: over 270M works, plus authors, sources, institutions and topics. Handy when you need literature search or one-hop citation walks without leaving the chat.
claude mcp add --transport http openalex-mcp-server https://openalex.caseyjhand.com/mcpWhat openalex-mcp-server does
Five tools cover the ground. openalex_search_entities queries and filters all eight entity types by ID or keyword; openalex_analyze_trends runs group-by aggregations; openalex_resolve_name turns a name or an identifier such as a DOI, ORCID, ROR, PMID or ISSN into an OpenAlex ID; openalex_get_citation_graph steps one hop along cites, cited_by or related_to; openalex_describe_fields lists the filter and group_by names an entity type accepts. Two prompts bundle the workflow: a systematic literature review and a research-landscape analysis.
Either connect over Streamable HTTP to the hosted endpoint https://openalex.caseyjhand.com/mcp, or run it locally through npx -y @cyanheads/openalex-mcp-server on STDIO. The local route reads OPENALEX_API_KEY, OPENALEX_MAILTO, OPENALEX_BASE_URL, OPENALEX_CLAMP_PER_PAGE and OPENALEX_FILTER_STRING_INPUT.
Filter syntax is where it bites. You may pass a record object or a native string like issn:0920-8542. A single value that combines | with an AND operator gets rejected as mixed_and_or_in_filter_value, so split the AND into its own key. Unquoted values also need matching double quotes.
What it helps with
- find recent open-access papers on a topic
- map a DOI or ORCID to its canonical OpenAlex ID
- see which works cite a given paper
- aggregate publication counts by institution
- run a literature review on an unfamiliar field
Example prompts for the agent
- Search openalex-mcp-server for papers on graph neural networks with open access and a recent year filter
- Resolve the DOI
10.1038/nature14539to its OpenAlex ID and show what cites it - Group publications by institution for the topic graph neural networks
How to install openalex-mcp-server
1Platform CLI: remote server
claude mcp add --transport http openalex-mcp-server https://openalex.caseyjhand.com/mcp2Platform CLI
claude mcp add --env OPENALEX_CLAMP_PER_PAGE=<OPENALEX_CLAMP_PER_PAGE> --env OPENALEX_FILTER_STRING_INPUT=<OPENALEX_FILTER_STRING_INPUT> --env OPENALEX_API_KEY=<OPENALEX_API_KEY> --env OPENALEX_MAILTO=<OPENALEX_MAILTO> --env OPENALEX_BASE_URL=<OPENALEX_BASE_URL> --transport stdio openalex-mcp-server -- npx -y @cyanheads/openalex-mcp-serverReplace <…> with your own values. 6 more environment variables are in the server README
1Platform CLI: remote server
codex mcp add openalex-mcp-server --url https://openalex.caseyjhand.com/mcp2Platform CLI
codex mcp add openalex-mcp-server --env OPENALEX_CLAMP_PER_PAGE=<OPENALEX_CLAMP_PER_PAGE> --env OPENALEX_FILTER_STRING_INPUT=<OPENALEX_FILTER_STRING_INPUT> --env OPENALEX_API_KEY=<OPENALEX_API_KEY> --env OPENALEX_MAILTO=<OPENALEX_MAILTO> --env OPENALEX_BASE_URL=<OPENALEX_BASE_URL> -- npx -y @cyanheads/openalex-mcp-serverReplace <…> with your own values. 6 more environment variables are in the server README
Config file
{
"mcpServers": {
"openalex-mcp-server": {
"url": "https://openalex.caseyjhand.com/mcp"
}
}
}{
"mcpServers": {
"openalex-mcp-server": {
"command": "npx",
"args": [
"-y",
"@cyanheads/openalex-mcp-server"
],
"env": {
"OPENALEX_CLAMP_PER_PAGE": "<OPENALEX_CLAMP_PER_PAGE>",
"OPENALEX_FILTER_STRING_INPUT": "<OPENALEX_FILTER_STRING_INPUT>",
"OPENALEX_API_KEY": "<OPENALEX_API_KEY>",
"OPENALEX_MAILTO": "<OPENALEX_MAILTO>",
"OPENALEX_BASE_URL": "<OPENALEX_BASE_URL>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README
Config file
{
"servers": {
"openalex-mcp-server": {
"type": "http",
"url": "https://openalex.caseyjhand.com/mcp"
}
}
}{
"servers": {
"openalex-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@cyanheads/openalex-mcp-server"
],
"env": {
"OPENALEX_CLAMP_PER_PAGE": "<OPENALEX_CLAMP_PER_PAGE>",
"OPENALEX_FILTER_STRING_INPUT": "<OPENALEX_FILTER_STRING_INPUT>",
"OPENALEX_API_KEY": "<OPENALEX_API_KEY>",
"OPENALEX_MAILTO": "<OPENALEX_MAILTO>",
"OPENALEX_BASE_URL": "<OPENALEX_BASE_URL>"
}
}
}
}Replace <…> with your own values. 6 more environment variables are in the server README
1Platform CLI: remote server
gemini mcp add -t http openalex-mcp-server https://openalex.caseyjhand.com/mcp2Platform CLI
gemini mcp add -e OPENALEX_CLAMP_PER_PAGE=<OPENALEX_CLAMP_PER_PAGE> -e OPENALEX_FILTER_STRING_INPUT=<OPENALEX_FILTER_STRING_INPUT> -e OPENALEX_API_KEY=<OPENALEX_API_KEY> -e OPENALEX_MAILTO=<OPENALEX_MAILTO> -e OPENALEX_BASE_URL=<OPENALEX_BASE_URL> openalex-mcp-server npx -y @cyanheads/openalex-mcp-serverReplace <…> with your own values. 6 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about openalex-mcp-server
How do I install openalex-mcp-server in Claude Code?
The hosted route takes one command: claude mcp add --transport http openalex-mcp-server https://openalex.caseyjhand.com/mcp. To run it locally instead, install via npx and pass the environment variables with --env on the same claude mcp add line.
What does openalex-mcp-server do?
It exposes OpenAlex to your agent: entity search and filtering, trend aggregation, name-to-ID resolution, citation-graph hops, and a field reference for filters.
Do I need environment variables for the local server?
OPENALEX_API_KEY, OPENALEX_MAILTO, OPENALEX_BASE_URL, OPENALEX_CLAMP_PER_PAGE and OPENALEX_FILTER_STRING_INPUT are the ones the STDIO setup reads. Setting OPENALEX_FILTER_STRING_INPUT=false forces filters to arrive as record objects only.
