@cyanheads/openalex-mcp-server

Public Hosted Server: https://openalex.caseyjhand.com/mcp

Tools

Four tools for querying the OpenAlex academic research catalog:

openalex_search_entities

Primary discovery and lookup tool. Covers all OpenAlex entity types (works, authors, sources, institutions, topics, keywords, publishers, funders).

• Retrieve a single entity by ID (OpenAlex ID, DOI, ORCID, ROR, PMID, PMCID, ISSN)

• Keyword search with boolean operators, quoted phrases, wildcards, and fuzzy matching

• Exact and AI semantic search modes

• Rich filter syntax: AND across fields, OR within fields (us|gb), NOT (!us), ranges (2020-2024), comparisons (>100)

• Sensible default field selection per entity type — prevents oversized responses; pass select to override

• Invalid select field names produce an error listing the valid fields for that entity type

• Formatted MCP output is a generic markdown renderer — every returned field is surfaced without per-entity-type hard-coding

• Cursor pagination, sorting, up to 100 results per page

openalex_analyze_trends

Aggregate entities into groups and count them for trend, distribution, and comparative analysis.

• Group by any supported field (publication year, OA status, institution, country, topic, etc.)

• Combine with filters to scope the population before aggregation

• Up to 200 groups per page with cursor pagination

• Supports include_unknown to show entities with no value for the grouped field

openalex_resolve_name

Name-to-ID resolution via autocomplete. Always use this before filtering by entity — names are ambiguous, IDs are not.

• Returns up to 10 matches with disambiguation hints

• Accepts partial names and DOIs for direct lookup

• Optional entity type filter and field-level filters

• ~200ms response time

openalex_get_citation_graph

One-hop citation graph traversal from a seed work. Wraps the OpenAlex cites/cited_by/related_to filters behind an explicit direction argument so callers do not have to know the filter names.

• cites: works that cite the seed (incoming citations)

• cited_by: works the seed cites (its reference list)

• related_to: OpenAlex algorithmic "related works" (~8-30 typical, may be empty for less-cited seeds)

• Accepts OpenAlex IDs, DOIs, PMIDs, PMCIDs as seed_id; validates the seed via a singleton /works/{id} lookup before walking, so non-existent seeds surface as NotFound

• Stacks with filters/sort/select to narrow the graph (e.g., publication_year=">2020", is_oa="true")

Prompts

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation

• Unified error handling across all tools

• Pluggable auth (none, jwt, oauth)

• Swappable storage backends via the framework (not currently used by this server)

• Structured logging with optional OpenTelemetry tracing

• Runs locally (stdio/HTTP) or in Docker from the same codebase

OpenAlex-specific:

• Typed API client with automatic ID normalization (DOI, ORCID, ROR, PMID, PMCID, ISSN, OpenAlex URLs)

• Abstract reconstruction from inverted indices — plaintext instead of OpenAlex's position-keyed encoding

• HTTP status codes mapped to specific MCP error classes (400/422 → InvalidParams, 429 → RateLimited, etc.) with upstream messages surfaced

• Timeout-aware request retries and cancellation support via AbortSignal

Getting Started

Public Hosted Instance

A public instance is available at https://openalex.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "openalex-mcp-server": {
      "type": "streamable-http",
      "url": "https://openalex.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add to your MCP client config (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "openalex-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/openalex-mcp-server"],
      "env": {
        "OPENALEX_API_KEY": "your-email@example.com"
      }
    }
  }
}

No API key needed — just provide your email to access the polite pool (10x faster rate limits).

Prerequisites

• Bun v1.3.0 or higher (for development)

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/openalex-mcp-server.git

2. Navigate into the directory:

cd openalex-mcp-server

3. Install dependencies:

bun install

Configuration

Running the Server

Local Development

• Build and run the production version:

  bun run build
  bun run start:http   # or start:stdio

• Run checks and tests:

  bun run devcheck     # Lints, formats, type-checks
  bun run test         # Runs test suite

Docker

docker build -t openalex-mcp-server .
docker run -e OPENALEX_API_KEY=your-key -p 3010:3010 openalex-mcp-server

Project Structure

Development Guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for logging, ctx.state for storage

• Always resolve names to IDs via openalex_resolve_name before using them in filters

Contributing

Issues and pull requests are welcome. Run checks before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.