# OpenAlex MCP Server

A Model Context Protocol (MCP) server that provides access to OpenAlex, a comprehensive open catalog of scholarly papers, authors, institutions, and more. Designed to empower AI assistants to conduct literature reviews, analyze research trends, and map the scholarly landscape.

## Quick Install

```bash
npx openalex-research-mcp setup
```

This auto-detects your Claude Desktop config, prompts for your email and optional API key, writes the config, and verifies connectivity — all in one step. Restart Claude Desktop when done.

**Flags:**
- `--print` — print the config JSON without writing anything
- `--config-path` — print the detected config file path and exit
- `--email you@example.com --api-key YOUR_KEY` — non-interactive / scripted mode

**Features:**
- ⚡️ **In-memory caching** with TTL for fast repeated requests
- 🔄 **Retry logic** with exponential backoff for resilient API calls
- ✅ **Input validation** with Zod schemas
- 🏥 **Health check** tool for monitoring
- 📊 **31 specialized tools** for research
- 🎓 **Curated journal presets** — UTD24, FT50, AJG/ABS tiers, top AI conferences, and more
- 🏛️ **Institution group presets** — Ivy League, Top US, INSEAD+London, and more

## Use as a Claude Skill (lightweight alternative)

The same OpenAlex access is also packaged as a **Claude Skill** under
[`skill/`](skill/) — a token-frugal alternative to the always-on MCP server.
A skill loads into the agent's context only when invoked and shells out to a
small zero-dependency CLI, so it costs nothing while idle. Use the **MCP server**
in MCP clients (Claude Desktop, TypingMind); use the **skill** in coding agents
(Claude Code, etc.) that already have shell access.

```bash
chmod +x skill/bin/openalex && export PATH="$PWD/skill/bin:$PATH"
export OPENALEX_EMAIL="you@example.com"     # optional: faster polite pool
openalex works "supply chain network" -n 5
```

See [`skill/README.md`](skill/README.md) for install and the MCP-vs-skill
trade-off. (The industry is steadily shifting routine API access from always-on
MCP servers toward on-demand skills — this repo ships both.)

## Features

Access 240+ million scholarly works through 31 specialized tools:

### Literature Search & Discovery
- **search_works**: Advanced search with Boolean operators, venue/journal filters, institution filters, citation thresholds, and sorting
- **get_work**: Get complete metadata for a specific work (all authors, full abstract, references)
- **get_related_works**: Find similar papers based on citations and topics
- **search_by_topic**: Explore literature in specific research domains
- **autocomplete_search**: Fast typeahead search for all entity types

### Credibility-Gated Search (Journal & Conference Presets)
- **list_journal_presets**: List all available named journal/conference and institution group presets
- **search_in_journal_list**: Search within a named preset list (UTD24, FT50, AJG 4*/4/3, top AI conferences, etc.) with optional institution filtering
- **search_works_in_venue**: Search within a specific venue by name, ISSN, or OpenAlex ID
- **get_top_venues_for_field**: Discover top journals/conferences in a field ranked by h-index
- **check_venue_quality**: Inspect h-index, impact, and indexing status of any venue

### Citation Analysis
- **get_work_citations**: Forward citation analysis (who cites this work)
- **get_work_references**: Backward citation analysis (what this work cites)
- **get_citation_network**: Build complete citation networks for visualization
- **get_top_cited_works**: Find the most influential papers in a field

### Author & Institution Analysis
- **search_authors**: Find researchers with h-index, citation metrics, and affiliations
- **search_authors_by_expertise**: Find leading experts in a topic ranked by h-index
- **get_author_profile**: Full research profile: h-index, i10-index, top works, recent works
- **get_author_works**: Analyze an author's publication history
- **get_author_collaborators**: Map co-authorship networks
- **search_institutions**: Find leading academic institutions

### High-Value Citation Finding
- **find_review_articles**: Find review papers and meta-analyses (high-value context citations)
- **find_seminal_papers**: Find foundational "must-cite" papers (high citation count, published 5+ years ago)
- **find_open_access_version**: Find freely available versions of papers with PDF links
- **batch_resolve_references**: Validate up to 20 DOIs/IDs at once

### Research Landscape & Trends
- **analyze_topic_trends**: Track research evolution over time
- **compare_research_areas**: Compare activity across different fields
- **get_trending_topics**: Discover emerging research areas
- **analyze_geographic_distribution**: Map global research activity

### Entity Lookup
- **get_entity**: Get detailed information for any OpenAlex entity
- **search_sources**: Find journals, conferences, and publication venues (sorted by h-index)

---

## Journal & Conference Presets

Presets let you restrict searches to credible, high-impact venues and institution groups without manually specifying ISSNs or names. Call `list_journal_presets` to see all available options at any time.

### Available Journal/Conference Presets

| Key | Name | Description |
|---|---|---|
| `utd24` | UT Dallas 24 | Official UTD journal list for business school rankings (34 journals) |
| `ft50` | FT50 Journals | Financial Times 50 journals for MBA/business school rankings |
| `abs4star` | AJG/ABS 4\* | World elite journals — the most prestigious tier in the ABS Guide |
| `abs4` | AJG/ABS 4 | Top international journals — excellent quality |
| `abs3` | AJG/ABS 3 | Internationally recognised journals — solid quality |
| `ms_misq_ops` | MS + IS + Operations | Management Science, M&SOM, MIS Quarterly, ISR, JMIS, OR, POM |
| `top_ai_conferences` | Top AI Conferences | NeurIPS, ICML, ICLR, AAAI, CVPR, ICCV, ACL, EMNLP, KDD, IJCAI |
| `top_cs_conferences` | Top CS Conferences | SOSP, OSDI, SIGCOMM, CHI, VLDB, SIGMOD, PLDI |
| `nature_science` | Nature & Science Family | Nature, Science, and branded sub-journals |

### Available Institution Group Presets

| Key | Name | Institutions |
|---|---|---|
| `harvard_stanford_mit` | Harvard / Stanford / MIT | Harvard, Stanford, MIT |
| `ivy_league` | Ivy League | All 8 Ivy League universities |
| `top_us` | Top US Research Universities | Harvard, Stanford, MIT, Berkeley, Caltech, Chicago, Princeton, Yale, Columbia, Penn |
| `top_us_business` | Top US Business Schools | Harvard, Stanford, Wharton, Booth, Kellogg, Sloan, Columbia, Stern, Darden, Tuck |
| `insead_london` | INSEAD + London Schools | INSEAD, LBS, Imperial, LSE, Oxford, Cambridge |
| `top_global_business` | Top Global Business Schools | Best of `top_us_business` + INSEAD, LBS, Oxford, Cambridge |
| `top_china` | Top Chinese Universities | Peking, Tsinghua, Fudan, SJTU, ZJU, CUHK, HKU |

### Example Preset Queries

```
# AI papers in UTD24 journals
search_in_journal_list(query="artificial intelligence", journal_list="utd24")

# AI papers in Management Science + M&SOM
search_in_journal_list(query="artificial intelligence", journal_list="ms_misq_ops")

# AI papers in FT50 journals since 2020
search_in_journal_list(query="artificial intelligence", journal_list="ft50", from_year=2020)

# AI papers in top AI conferences
search_in_journal_list(query="artificial intelligence", journal_list="top_ai_conferences")

# AI papers in AJG 4* journals
search_in_journal_list(query="artificial intelligence", journal_list="abs4star")

# AI papers in UTD24 journals by Harvard/Stanford/MIT authors
search_in_journal_list(query="artificial intelligence", journal_list="utd24", institution_group="harvard_stanford_mit")

# AI papers by professors at INSEAD
search_works(query="artificial intelligence", author_institution="INSEAD")

# AI papers by anyone from Harvard, Stanford, or MIT
search_works(query="artificial intelligence", institution_group="harvard_stanford_mit")
```

### Requesting Additional Presets

> **📬 Want a new journal group added?**
> The preset lists (UTD24, FT50, AJG tiers, etc.) are curated in the source code. If your field uses a different ranking system — ABDC, VHB-JQ, CNRS, Norwegian list, discipline-specific lists, or any custom journal group — **open a GitHub issue** and I will add it. Include the list name, a short description, and the ISSNs or venue names. Community contributions via pull requests are also very welcome.

## Installation

### Option 1: Install from npm (Recommended)

```bash
# Install globally
npm install -g openalex-research-mcp

# Or use directly with npx (no installation needed)
npx openalex-research-mcp
```

### Option 2: Install from source

```bash
# Clone the repository
git clone https://github.com/oksure/openalex-research-mcp.git
cd openalex-research-mcp

# Install dependencies
npm install

# Build the TypeScript code
npm run build
```

## Configuration

### Environment Variables (Optional but Recommended)

Set your email to join the "polite pool" for better rate limits:

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

For premium users with an API key:

```bash
export OPENALEX_API_KEY="your-api-key"
```

### Claude Desktop Configuration

Add to your Claude Desktop config file:

**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude\claude_desktop_config.json`

> **Tip:** In Claude Desktop, go to **File → Settings → Developer → Edit Config** to open the correct config file directly. The `npx openalex-research-mcp setup` command also auto-detects the path.

**If you installed via npm/npx:**
```json
{
  "mcpServers": {
    "openalex": {
      "command": "npx",
      "args": ["-y", "openalex-research-mcp"],
      "env": {
        "OPENALEX_EMAIL": "your.email@example.com"
      }
    }
  }
}
```

**If you installed from source:**
```json
{
  "mcpServers": {
    "openalex": {
      "command": "node",
      "args": ["/absolute/path/to/openalex-research-mcp/build/index.js"],
      "env": {
        "OPENALEX_EMAIL": "your.email@example.com"
      }
    }
  }
}
```

### TypingMind and Other MCP Clients

The same configuration format works for TypingMind and other MCP-compatible clients.

> **⚠️ TypingMind Users**: If you encounter "tool_use_id" errors, see [TYPINGMIND.md](TYPINGMIND.md) for troubleshooting steps and best practices. **TL;DR**: Start a new chat, request fewer results (5-10), and use specific queries with filters.

## Usage Examples

### Example 1: Literature Review for AI Safety

```
Find the most influential papers on AI safety published since 2020
```

The assistant will use `get_top_cited_works` with appropriate filters to find highly-cited papers in AI safety research. The tool automatically filters for papers with at least 50 citations by default, ensuring results focus on influential work. For the most impactful papers, you can specify a higher threshold like `min_citations: 200`.

### Example 2: Citation Network Analysis

```
Get the citation network for the paper "Attention Is All You Need" (DOI: 10.48550/arXiv.1706.03762)
```

The assistant will use `get_citation_network` to build a network of citing and referenced papers, enabling visualization of research impact.

### Example 3: Research Trend Analysis

```
Show me how quantum computing research has evolved over the past 10 years
```

The assistant will use `analyze_topic_trends` to group publications by year and show growth patterns.

### Example 4: Finding Collaborators

```
Who are the main collaborators of Geoffrey Hinton?
```

The assistant will use `get_author_collaborators` to analyze co-authorship patterns.

### Example 5: Comparative Research Analysis

```
Compare research activity in "deep learning", "reinforcement learning", and "federated learning" from 2018-2024
```

The assistant will use `compare_research_areas` to show relative publication volumes.

### Example 6: Geographic Research Mapping

```
Which countries are leading research in climate change mitigation?
```

The assistant will use `analyze_geographic_distribution` to map research activity by country.

### Example 7: Top-Journal Citation Search

```
Find influential papers on "large language models" published in UTD24 journals since 2020
```

The assistant will use `search_in_journal_list` with `journal_list="utd24"` and `from_year=2020`.

### Example 8: Institution-Filtered Search

```
Find papers on supply chain resilience published by researchers at Harvard, Stanford, or MIT
```

The assistant will use `search_works` with `institution_group="harvard_stanford_mit"`.

### Example 9: Seminal Paper Discovery

```
What are the must-cite foundational papers in transformer models?
```

The assistant will use `find_seminal_papers` with `min_citations=500` to find highly-cited, older foundational works.

### Example 10: Expert Discovery

```
Who are the top researchers in reinforcement learning, and where are they based?
```

The assistant will use `search_authors_by_expertise` with `topic="reinforcement learning"`, sorted by h-index.

## Response Format

The MCP server uses a **two-tier response system** to balance performance and completeness:

### Summarized Responses (Search Results)

For list operations (`search_works`, `get_citations`, `get_author_works`, etc.), responses include only essential information:

**Included:**
- Core identifiers (ID, DOI, title)
- Publication metadata (year, date, type)
- Citation metrics (cited_by_count)
- First 5 authors (with `authors_truncated` flag if more exist)
- Primary topic classification
- Open access status and URLs
- Source/journal name
- Abstract preview (first 500 chars)

**Excluded to reduce size:**
- Full author lists beyond 5 authors
- All secondary topics/concepts
- Complete affiliation details
- Full reference lists
- Detailed bibliographic data

This optimization reduces response sizes by ~80-90% (from ~10 KB to ~1.7 KB per work), making the server compatible with all MCP clients including TypingMind and Claude Desktop.

### Full Details (`get_work` tool)

When you need **complete information** about a specific paper, use the `get_work` tool with a work ID or DOI. This returns:

**Complete Author Information:**
- ALL authors (not just first 5)
- Position indicators (first, middle, last author)
- Institutions and affiliations
- ORCID IDs
- Corresponding author flags
- Country information

**Complete Content:**
- Full abstract (reconstructed from OpenAlex index)
- All topics (not just primary)
- Complete bibliographic data
- Funding and grant information
- Keywords
- Complete reference and citation lists

**Use Cases:**
- Identifying PIs (often last author in biomedical fields)
- Finding corresponding authors
- Getting complete author affiliations
- Accessing full abstracts
- Comprehensive paper analysis

## Tool Reference

### Search Parameters

Most search tools support these common parameters:

- **from_year / to_year**: Filter by publication year range
- **min_citations**: Minimum citation count (e.g., `50` for solid papers, `200` for highly influential)
- **cited_by_count**: Citation filter with operator (e.g., `">100"`) — prefer `min_citations` for simplicity
- **source_name / source_issn / source_id**: Filter by journal or conference
- **author_institution**: Filter by author institution name (pipe-separated for OR, e.g., `"Harvard University|MIT"`)
- **institution_group**: Named institution group preset (e.g., `harvard_stanford_mit`)
- **is_oa**: Filter for open access works only
- **sort**: Sort results (`relevance_score`, `cited_by_count:desc`, `publication_year:desc`)
- **page / per_page**: Pagination (max 200 per page; default 10, use 20 for broader coverage)

### Boolean Search

The `search_works` and related tools support Boolean operators:

```
"machine learning" AND (ethics OR fairness)
"climate change" NOT "climate denial"
(AI OR "artificial intelligence") AND safety
```

### Identifiers

OpenAlex accepts multiple identifier formats:

- **OpenAlex IDs**: W2741809807, A5023888391
- **DOIs**: 10.1371/journal.pone.0000000
- **ORCIDs**: 0000-0001-2345-6789
- **URLs**: Full OpenAlex URLs

## API Rate Limits

- **Default**: 100,000 requests/day, 10 requests/second
- **Polite Pool** (with email): Better performance and reliability
- **Premium** (with API key): Higher limits and exclusive filters

## Development

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

# Build
npm run build

# Run
npm start
```

## Data Source

All data comes from [OpenAlex](https://openalex.org), an open and comprehensive catalog of scholarly papers, authors, institutions, and more. OpenAlex indexes:

- 240+ million works (papers, books, datasets)
- 50,000+ new works added daily
- Full citation network and metadata
- Author affiliations and collaboration data
- Publication venues and impact metrics

## Use Cases

This MCP server is ideal for:

- **Literature Reviews**: Systematically search and analyze research papers
- **Citation Analysis**: Understand research impact and influence
- **Trend Analysis**: Track how research topics evolve over time
- **Collaboration Mapping**: Identify research networks and partnerships
- **Gap Analysis**: Find understudied areas in research
- **Comparative Studies**: Compare research activity across fields
- **Institution Benchmarking**: Analyze research output by institution
- **Author Profiling**: Study researcher publication patterns

## License

MIT

## Contributing

Contributions are welcome! Here's how to get involved:

### Reporting bugs

- Search [existing issues](https://github.com/oksure/openalex-research-mcp/issues) before opening a new one.
- Include a clear description of what you expected vs. what happened.
- If the bug involves an API call, paste the relevant curl command or error message so it can be reproduced quickly (see the [OpenAlex API docs](https://docs.openalex.org) for reference).

### Requesting features

- Open an issue with the `enhancement` label.
- Describe the use case and, if possible, sketch the desired tool name, input parameters, and example output.

### Submitting pull requests

1. **Fork** the repo and create a branch from `master` (e.g. `fix/my-bug` or `feat/my-feature`).
2. **Make your changes** following the patterns in [CLAUDE.md](CLAUDE.md) (two-layer architecture, `summarizeWork` for list results, `getFullWorkDetails` for single-work lookups, etc.).
3. **Add tests** — run `npm test` (vitest) to make sure all 26+ existing tests still pass, and add new tests in `tests/` for any new behaviour.
4. **Build** with `npm run build` to confirm there are no TypeScript errors.
5. **Open a PR** against `master` with a clear description of the problem and fix, including any curl-level reproduction steps for API-related bugs.

> **Note on API quirks:** Before adding new filter logic, check the "OpenAlex API Quirks & Common Bugs" section in [CLAUDE.md](CLAUDE.md) — several non-obvious behaviours (date filters, sort suffixes, DOI encoding) are documented there.

## Resources

- [OpenAlex Documentation](https://docs.openalex.org)
- [OpenAlex API](https://docs.openalex.org/how-to-use-the-api/api-overview)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP Specification](https://spec.modelcontextprotocol.io)