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)

npm install -g openalex-mcp

From Source

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:

{
  "mcpServers": {
    "openalex": {
      "command": "npx",
      "args": ["openalex-mcp"]
    }
  }
}

json

Or if installed locally:

{
  "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

{
  "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": "[email protected]"
  }
}

Find authors by institution

{
  "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

{
  "tool": "search_works",
  "arguments": {
    "filter": "concepts.id:C154945302",
    "group_by": "publication_year"
  }
}

Autocomplete journal names

{
  "tool": "autocomplete",
  "arguments": {
    "search": "nature",
    "type": "sources",
    "per_page": 5
  }
}

Classify research text

{
  "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:

{
  "meta": {
    "count": 249256387,
    "db_response_time_ms": 12,
    "page": 1,
    "per_page": 25,
    "next_cursor": "ZjEwMD..."
  },
  "results": [
    {
      /* entity object */
    }
  ]
}

Development

# 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:

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:

{
  "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. 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