OpenAlex MCP Server

# OpenAlex MCP Server A Model Context Protocol (MCP) server that provides access to the OpenAlex API - a fully open catalog of the global research system covering over 240 million scholarly works. ## Features This MCP server provides tools to search and retrieve: - **Works** - Scholarly articles, preprints, datasets, books (240M+ items) - **Authors** - Researchers and creators with ORCID integration - **Sources** - Journals, conferences, repositories (~250K venues) - **Institutions** - Universities, hospitals, labs with ROR matching - **Concepts** - Hierarchical research topics (levels 0-5) - **Publishers** - Publishing organizations - **Funders** - Grant-making bodies - **Autocomplete** - Type-ahead search across all entity types - **Text Classification** - Concept prediction for arbitrary text ## Installation ### From npm (Recommended) ```bash npm install -g openalex-mcp ``` ### From Source ```bash git clone https://github.com/reetp14/openalex-mcp.git cd openalex-mcp npm install npm run build ``` ## Usage ### As an MCP Server Add to your MCP client configuration: ```json { "mcpServers": { "openalex": { "command": "npx", "args": ["openalex-mcp"] } } } json ``` Or if installed locally: ```json { "mcpServers": { "openalex": { "command": "node", "args": ["./node_modules/openalex-mcp/build/index.js"] } } } ``` ### Available Tools #### Entity Search Tools All search tools support the full OpenAlex query grammar: - `search_works` - Search scholarly works - `search_authors` - Search researchers and creators - `search_sources` - Search journals, conferences, repositories - `search_institutions` - Search universities, hospitals, labs - `search_concepts` - Search research topics - `search_publishers` - Search publishing organizations - `search_funders` - Search grant-making bodies **Common Parameters:** - `search` - Full-text search query - `filter` - Boolean filters (e.g., `concept.id:C12345,from_publication_date:2022-01-01`) - `sort` - Sort field with optional `:desc` (e.g., `cited_by_count:desc`) - `page`/`per_page` - Standard pagination (max 10,000 results total) - `cursor` - Deep pagination (use `*` for first call) - `group_by` - Faceting/aggregation by field - `select` - Comma-separated fields to return - `sample` - Random sample size with optional `seed` - `mailto` - Your email for higher rate limits #### Single Entity Retrieval - `get_entity` - Get a single entity by OpenAlex ID - `entity_type` - One of: works, authors, sources, institutions, concepts, publishers, funders - `openalex_id` - OpenAlex ID (e.g., W2741809807, A1969205038) #### Utility Tools - `autocomplete` - Type-ahead search across entity types - `search` - Search query (required) - `type` - Entity type to search within (optional) - `per_page` - Number of suggestions (max 50) - `classify_text` - Predict research concepts from text - `title` - Title text to classify - `abstract` - Abstract text to classify ## Examples ### Search for AI papers from 2023 ```json { "tool": "search_works", "arguments": { "search": "artificial intelligence", "filter": "from_publication_date:2023-01-01,to_publication_date:2023-12-31", "sort": "cited_by_count:desc", "per_page": 10, "mailto": "researcher@university.edu" } } ``` ### Find authors by institution ```json { "tool": "search_authors", "arguments": { "filter": "last_known_institution.id:I27837315", "sort": "works_count:desc", "select": "id,display_name,works_count,cited_by_count" } } ``` ### Get publication trends by year ```json { "tool": "search_works", "arguments": { "filter": "concepts.id:C154945302", "group_by": "publication_year" } } ``` ### Autocomplete journal names ```json { "tool": "autocomplete", "arguments": { "search": "nature", "type": "sources", "per_page": 5 } } ``` ### Classify research text ```json { "tool": "classify_text", "arguments": { "title": "Deep Learning for Medical Image Analysis", "abstract": "We present a novel approach using convolutional neural networks..." } } ``` ## Query Grammar Quick Reference ### Filters - Chain with `,` for AND: `concept.id:C12345,publication_year:2023` - Chain with `|` for OR: `type:journal|type:repository` - Negate with `!`: `authors.id!A12345` (exclude author) - Date ranges: `from_publication_date:2020-01-01,to_publication_date:2023-12-31` ### Sorting - Ascending: `sort=publication_year` - Descending: `sort=cited_by_count:desc` - Multiple: `sort=publication_year:desc,cited_by_count:desc` ### Pagination - Standard: `page=2&per_page=100` (max 10,000 results) - Deep: `cursor=*` (first call), then use returned `next_cursor` ### Rate Limits - Anonymous: 10 requests/second, 100,000/day - With `mailto`: 100 requests/second, 1,000,000/day ## API Response Format All tools return the standard OpenAlex JSON envelope: ```json { "meta": { "count": 249256387, "db_response_time_ms": 12, "page": 1, "per_page": 25, "next_cursor": "ZjEwMD..." }, "results": [ { /* entity object */ } ] } ``` ## Development ```bash # Watch mode during development npm run watch # Test with MCP inspector npm run inspector # Run basic functionality test node test-simple.js ``` ## Environment Configuration The server supports environment variables for configuration. Copy `.env.example` to `.env` and configure: ```bash cp .env.example .env # Edit .env with your settings ``` ### Environment Variables - `OPENALEX_BEARER_TOKEN`: Bearer token for authenticated API access (optional) - `OPENALEX_DEFAULT_EMAIL`: Default email for rate limiting when no `mailto` parameter provided ## API Access Notes - **Free Access**: OpenAlex API is free and open - **Rate Limits**: 10 req/sec (anonymous) or 100 req/sec (with Bearer token or `mailto`) - **Authentication**: Bearer token automatically loaded from environment - **Response Size**: Use `select` parameter to limit response size for large datasets Example with optimized response: ```json { "tool": "search_works", "arguments": { "search": "machine learning", "select": "id,display_name,publication_year,cited_by_count", "per_page": 10 } } ``` ## About OpenAlex OpenAlex is a fully open catalog of the global research system, named after the ancient Library of Alexandria and created by the nonprofit [OurResearch](https://ourresearch.org/). It provides free, comprehensive metadata about scholarly works, authors, institutions, and more. - Website: https://openalex.org/ - API Documentation: https://docs.openalex.org/ - Data sources: Crossref, ORCID, ROR, Microsoft Academic Graph, and more