# 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