mcp-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
• [x] Scan code base for dead code
• [x] Add mermaid documentation
• [x] Unify concepts names (ie. Articles/Works)
• [x] Two levels of formating details in filter: low (current one), medium (for fetch_* tools)

Tools Evolutions

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

in format_work_result add:

• [x] first 3 Authors
• [x] Primary topic classification

in _process_fulltext in fetch_work

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

Search

• [x] 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

• [x] 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