# OpenAlex MCP Server

An MCP (Model Context Protocol) server that provides access to [OpenAlex](https://openalex.org), a free and open catalog of the world's scholarly works, authors, institutions, and more.

## Features

- **Search 250M+ scholarly works** with full-text search and powerful filters
- **Author discovery** with publication metrics (h-index, i10-index, citations)
- **Institution profiles** for universities, research labs, and companies
- **Citation network traversal** — find what cites a paper and what it cites
- **Multiple ID format support** — OpenAlex IDs, DOIs, PMIDs, ORCIDs, RORs

## Installation

```bash
# Clone or copy the project
cd openalex-mcp-server

# Install dependencies
npm install

# Build the TypeScript
npm run build
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `OPENALEX_EMAIL` | Email for polite pool (higher rate limits) | `user@example.com` |
| `TRANSPORT` | Transport type: `stdio` or `http` | `stdio` |
| `PORT` | Port for HTTP transport | `3000` |

Set your email to get into OpenAlex's "polite pool" with higher rate limits:

```bash
export OPENALEX_EMAIL="your.email@example.com"
```

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "openalex": {
      "command": "node",
      "args": ["/path/to/openalex-mcp-server/dist/index.js"],
      "env": {
        "OPENALEX_EMAIL": "your.email@example.com"
      }
    }
  }
}
```

### With Claude Code

```bash
claude mcp add openalex node /path/to/openalex-mcp-server/dist/index.js
```

### Standalone (HTTP mode)

```bash
TRANSPORT=http PORT=3000 npm start
```

## Available Tools

### Works (Publications)

| Tool | Description |
|------|-------------|
| `openalex_search_works` | Search works with full-text queries and filters |
| `openalex_get_work` | Get a single work by OpenAlex ID, DOI, or PMID |
| `openalex_get_citations` | Get works that cite a given work |
| `openalex_get_references` | Get works cited by a given work |

### Authors

| Tool | Description |
|------|-------------|
| `openalex_search_authors` | Search authors by name |
| `openalex_get_author` | Get author profile by OpenAlex ID or ORCID |
| `openalex_get_author_works` | Get an author's publications |

### Institutions

| Tool | Description |
|------|-------------|
| `openalex_search_institutions` | Search institutions by name |
| `openalex_get_institution` | Get institution profile by OpenAlex ID or ROR |
| `openalex_get_institution_works` | Get an institution's publications |

## Example Queries

### Search for recent CRISPR papers

```
openalex_search_works(
  query: "CRISPR gene therapy",
  filter: "publication_year:2023,open_access.is_oa:true",
  sort: "cited_by_count:desc"
)
```

### Find highly-cited climate research

```
openalex_search_works(
  query: "climate change",
  filter: "cited_by_count:>1000,type:review"
)
```

### Get citation network for a paper

```
// Get the paper
openalex_get_work(id: "10.1038/s41586-020-2649-2")

// Get papers that cite it
openalex_get_citations(id: "10.1038/s41586-020-2649-2")

// Get papers it cites
openalex_get_references(id: "10.1038/s41586-020-2649-2")
```

### Explore an author's profile

```
openalex_search_authors(query: "Fei-Fei Li")
openalex_get_author(id: "A5023888391")
openalex_get_author_works(id: "A5023888391", sort: "cited_by_count:desc")
```

### Find Northwestern University's research output

```
openalex_search_institutions(query: "Northwestern University")
openalex_get_institution(id: "I111979921")
openalex_get_institution_works(
  id: "I111979921",
  filter: "publication_year:2024",
  sort: "cited_by_count:desc"
)
```

## Filter Syntax

OpenAlex supports powerful filtering. Common filters:

| Filter | Examples |
|--------|----------|
| `publication_year` | `2023`, `2020-2024` |
| `open_access.is_oa` | `true`, `false` |
| `cited_by_count` | `>100`, `<10`, `100-500` |
| `type` | `article`, `book`, `preprint`, `dataset` |
| `authorships.institutions.id` | `I27837315` (filter by institution) |
| `authorships.author.id` | `A5023888391` (filter by author) |
| `primary_location.source.id` | `S137773608` (filter by journal) |

Combine multiple filters with commas:
```
filter: "publication_year:2023,open_access.is_oa:true,cited_by_count:>50"
```

## Response Formats

All tools support two response formats:

- **`markdown`** (default): Human-readable formatted output
- **`json`**: Structured data for programmatic use

## Rate Limits

- Without email: ~10 requests/second
- With email (polite pool): ~100 requests/second

Always set `OPENALEX_EMAIL` for production use.

## Development

```bash
# Watch mode for development
npm run dev

# Build for production
npm run build

# Run the server
npm start
```

## License

MIT

## Links

- [OpenAlex Documentation](https://docs.openalex.org)
- [OpenAlex API](https://api.openalex.org)
- [MCP Specification](https://modelcontextprotocol.io)