openalex-mcp

openalex-mcp

Connects AI agents to the OpenAlex scholarly database, enabling search and retrieval of works, authors, institutions, and sources via natural language.

Category
访问服务器

README

OpenAlex MCP Server

Connects any MCP-compatible AI agent to OpenAlex — the world's largest free and open scholarly database with 250+ million works, 300+ million authors, 100,000+ institutions, and billions of citation links.

Works with: Claude Desktop · Claude Code · Cursor · VS Code Copilot · Windsurf · Zed · any MCP client

No paywall. No institutional access required. CC0 licensed data.

Quickstart (2 minutes)

1. Get your free API key at openalex.org/settings/api — takes 30 seconds

2. Install the server

pip install openalex-mcp

3. Add to your AI agent — copy your client's config from Configuration below.

Prerequisites

Python 3.11+

python --version   # needs 3.11 or higher
# Install if missing: https://python.org/downloads

uv (recommended)

# Windows
winget install astral-sh.uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

No uv? Use pip install openalex-mcp instead, then replace uvx openalex-mcp in configs with the path from where openalex-mcp (Windows) or which openalex-mcp (macOS/Linux).

Installation Options

Option A — uvx (recommended)

uvx openalex-mcp          # install and run — uv handles everything
uv tool upgrade openalex-mcp  # upgrade later

Option B — pip

pip install openalex-mcp
which openalex-mcp    # macOS/Linux → /usr/local/bin/openalex-mcp
where openalex-mcp    # Windows    → C:\Users\YOU\AppData\...

Option C — From source

git clone https://github.com/JOSETRA44/openalex-mcp.git
cd openalex-mcp
uv sync
cp .env.example .env   # edit .env with your key
uv run openalex-mcp    # run directly

Environment Variables

Variable Required Default Description
OPENALEX_API_KEY Recommended — Free API key from openalex.org/settings/api
OPENALEX_EMAIL Alt to key — Your email — uses the "polite pool" (slower but free, no key)
OPENALEX_CACHE_TTL No 300 Response cache duration in seconds (0 = disabled)
OPENALEX_MAX_RETRIES No 3 Retries on rate-limit errors
LOG_LEVEL No INFO DEBUG · INFO · WARNING · ERROR

Either OPENALEX_API_KEY or OPENALEX_EMAIL is required. The API key gives 10× more daily quota ($1/day free).

Configuration by Client

Replace YOUR_API_KEY_HERE with your actual key in all configs below.

Claude Desktop

Config file:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "openalex": {
      "command": "uvx",
      "args": ["openalex-mcp"],
      "env": {
        "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Restart Claude Desktop after saving. You'll see a hammer icon (🔨) confirming tools are loaded.

Claude Code (CLI)

Add to your project's .mcp.json in the repo root:

{
  "mcpServers": {
    "openalex": {
      "command": "uvx",
      "args": ["openalex-mcp"],
      "env": {
        "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Or from source (local development):

{
  "mcpServers": {
    "openalex": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/openalex-mcp",
        "run", "openalex-mcp"
      ],
      "env": {
        "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Verify with /mcp in the Claude Code prompt — you should see openalex with 9 tools.

Cursor

Config file: .cursor/mcp.json in project root, or globally:

  • Windows: %APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp.json
  • macOS: ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp.json
{
  "mcpServers": {
    "openalex": {
      "command": "uvx",
      "args": ["openalex-mcp"],
      "env": {
        "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Settings → Features → MCP → toggle on → reload window.

VS Code + GitHub Copilot

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "openalex": {
      "type": "stdio",
      "command": "uvx",
      "args": ["openalex-mcp"],
      "env": {
        "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Ctrl+Shift+P → GitHub Copilot: Configure MCP

Windsurf

Config file:

  • Windows: %APPDATA%\Codeium\windsurf\mcp_config.json
  • macOS: ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "openalex": {
      "command": "uvx",
      "args": ["openalex-mcp"],
      "env": {
        "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Zed

Edit ~/.config/zed/settings.json:

{
  "context_servers": {
    "openalex": {
      "command": {
        "path": "uvx",
        "args": ["openalex-mcp"],
        "env": {
          "OPENALEX_API_KEY": "YOUR_API_KEY_HERE"
        }
      }
    }
  }
}

Continue.dev

Edit .continue/config.yaml:

mcpServers:
  - name: openalex
    command: uvx
    args:
      - openalex-mcp
    env:
      OPENALEX_API_KEY: "YOUR_API_KEY_HERE"

Any other MCP client (generic stdio)

command: uvx
args:    ["openalex-mcp"]
env:     OPENALEX_API_KEY=YOUR_API_KEY_HERE

Automated Setup Script

Auto-detect your installed clients and configure them:

# Interactive
python setup_mcp.py

# Non-interactive — configure all detected clients
python setup_mcp.py --key YOUR_API_KEY_HERE --yes

# Preview without writing files
python setup_mcp.py --key YOUR_API_KEY_HERE --dry-run --yes

# Show detected clients only
python setup_mcp.py --list

The script backs up existing config files before modifying them.

Available Tools (9 total)

Tool What it does
openalex_search_works Keyword + filter search over 250M+ scholarly works
openalex_get_work Full metadata for one work (by OpenAlex ID, DOI, or PubMed ID)
openalex_search_authors Find researchers by name, institution, ORCID, or metrics
openalex_get_author Author profile: h-index, i10-index, citations by year, topics
openalex_search_institutions Search universities and research organizations by name/country
openalex_get_institution Institution details: country, type, h-index, top topics
openalex_search_sources Search journals, conferences, and repositories
openalex_get_source Source details: ISSN, publisher, OA status, h-index
openalex_aggregate_works Group/count works by year, type, country, topic, etc.

MCP Resource

Resource Contents
openalex://filter-reference Complete filter syntax: 100+ field codes, operators, and examples

Example Queries

# Find recent papers on a topic
openalex_search_works(
    query="federated learning privacy",
    filters="publication_year:>2021,type:article",
    sort="cited_by_count:desc"
)

# Get full paper details by DOI
openalex_get_work("10.1038/s41586-021-03819-2")

# Find an author and get their profile
openalex_search_authors(query="Geoffrey Hinton")
openalex_get_author("A2208157607")

# Find an institution, then see its recent output
openalex_search_institutions(query="UNAM", country_code="MX")
openalex_search_works(
    filters="institutions.id:I865918315,publication_year:>2020",
    sort="cited_by_count:desc"
)

# Annual publication trend for a topic
openalex_aggregate_works(
    group_by="publication_year",
    filters="type:article",
    query="machine learning"
)

# Find open-access journals in a field
openalex_search_sources(
    query="bioinformatics",
    is_oa=True,
    source_type="journal"
)

Filter Quick Reference

Pattern Example
Year range publication_year:2020-2024
Newer than publication_year:>2021
Work type type:article · type:preprint · type:book
Open access only open_access.is_oa:true
Highly cited cited_by_count:>100
By institution institutions.id:I97018004
By country institutions.country_code:US
In a journal primary_location.source.id:S137773608
By language language:en · language:es · language:zh
Papers citing a work cites:W2741809807
Has DOI has_doi:true
Has abstract has_abstract:true

For the full filter reference, read the openalex://filter-reference resource or see developers.openalex.org.

Rate Limits & Quotas

Auth method Daily budget Calls/second
API key (free) $1.00/day ~10
Email (polite pool) $0.10/day ~3
No auth $0.10/day ~1

The server tracks rate-limit headers and automatically sleeps when the quota is low.

Action costs (free tier):

Action Daily allowance
Get single entity (by ID/DOI) Unlimited
List + filter 10,000 calls / 1M results
Full-text search 1,000 calls / 100K results

Tip: Use openalex_get_work (unlimited) for single-record lookups rather than search.

Verify It's Working

MCP Inspector (interactive UI)

npx @modelcontextprotocol/inspector uvx openalex-mcp

Open the URL, click Connect, List Tools — you should see all 9 tools.

Quick smoke test

echo "" | OPENALEX_API_KEY=your_key uvx openalex-mcp
# Should start without errors, then exit when stdin closes

Run unit tests (source install)

uv sync --group dev
uv run pytest tests/ -v
# Expected: 28 passed

Troubleshooting

"Configuration error: Set OPENALEX_API_KEY..."

Add OPENALEX_API_KEY to your MCP client's env block. Get a free key at openalex.org/settings/api.

"command not found: uvx"

Install uv: docs.astral.sh/uv

401 error

API key is invalid. Regenerate at openalex.org/settings/api.

404 error on a work/author/institution

The identifier may be wrong. Try looking up the entity with a search tool first, then use the returned openalex_id.

"uvx openalex-mcp" slow on first run

uv is downloading and caching the package — subsequent starts are instant (~0.2s).

Tools appear but return empty results

Broaden your query: remove publication_year filters, or try query= instead of filters=.

vs. Scopus / Web of Science

OpenAlex Scopus Web of Science
Cost Free Subscription Subscription
Coverage 250M+ works 90M works 170M works
Open data CC0 Proprietary Proprietary
API quota 10K calls/day 20K/week Limited
Non-English Excellent Good Fair
Full-text links Yes Partial Partial

Project Structure

openalex-mcp/
├── src/openalex_mcp/
│   ├── server.py           # FastMCP entry point
│   ├── config.py           # Env var configuration (pydantic-settings)
│   ├── client.py           # Async HTTP client + TTL cache + rate limiting
│   ├── exceptions.py       # Error hierarchy
│   ├── formatters.py       # Raw OpenAlex JSON → clean AI-friendly dicts
│   ├── tools/              # 9 MCP tools (works, authors, institutions, sources, aggregate)
│   └── resources/          # openalex://filter-reference static resource
├── openalex-researcher/    # Agent skill
│   ├── SKILL.md
│   └── references/         # Filter syntax, workflows, output reference
├── tests/                  # Unit tests (28 cases, no network required)
├── setup_mcp.py            # Automated config installer
├── .env.example            # Environment variable template
└── pyproject.toml          # Package definition

License

MIT — see LICENSE

Data from OpenAlex is CC0 (public domain).

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选