Openalex

MCP server for the OpenAlex scholarly database. Gives AI agents tools to search and retrieve academic works, authors, and institutions.

Requirements

• Python >= 3.12
• uv
• OpenAlex API key (get one for free)

Installation

git clone https://github.com/ELumya/openalex-mcp.git
cd openalex-mcp
uv sync

Configuration

Copy the example env file and set your API key:

cp .env.example .env
# edit .env and set OPENALEX_API_KEY=your-key-here

Running

STDIO (default — for local MCP clients):

uv run fastmcp run src/server.py

HTTP transport:

MCP_TRANSPORT=http MCP_HOST=127.0.0.1 MCP_PORT=8000 uv run fastmcp run src/server.py

MCP Tools

Tool	Description
search_works	Search works with filters (institution, year, date range, type, peer-reviewed)
semantic_search_works	Find works similar to a text using AI semantic search (matches by meaning)
fetch_work	Fetch full work metadata by OpenAlex ID or DOI — optionally extract PDF or request an LLM summary
search_authors	Search author profiles by name or ORCID
fetch_author	Fetch full author profile by OpenAlex ID or ORCID
get_author_works	List all publications by a specific author
search_institutions	Search institutions by name, country, or type
fetch_institution	Fetch full institution profile by OpenAlex ID or ROR

Architecture

See ARCHITECTURE.md for system overview, module dependency graph, and tool flow diagrams.

TODOs

• Add tests
• Add CI/CD
• Use cache for high rate requests
• Scan code base for dead code
• Add mermaid documentation
• Unify concepts names (ie. Articles/Works)
• Two levels of formating details in filter: low (current one), medium (for fetch_* tools)

Tools Evolutions

• Test OpenAlex support of Elasticsearch: YES!
• Update work search tools descriptions, add: "Elasticsearch syntax"
• Update tools descriptions, do not explain how it works but what you need to pass.
• Update Author search tool, remove IDs handling (use fetch_author for this)

in format_work_result add:

• first 3 Authors
• Primary topic classification

in _process_fulltext in fetch_work

• Remove pure PDF handling, auto-detect format based on prompt presence (if prompt provided → LLM summary, else → markdown)
• Use proper sampling parameters

Search

• Semantic search, added as a new tool but can easily be integrated to work_search, we perform modifications at filters build_works_query.
• Search by topics
• Search foundational works

Citation

• graph_work_citations

Authors

• get_author_works: parameter author replaced by author_id; accepts only OpenAlex ID or ORCID.
• graph_collaborations

Institutions

• graph_colaborations

Global analysis tools

• OpenAlex Topic comparaison
• Geographical Region comparaison
• Institutions comparaison
• Trend deep analysis

License

MIT