OpenAlex + PubMed MCP Server

发布简介（中文） OpenAlex MCP Server 是一个轻量的 MCP（Model Context Protocol）服务端，提供学术文献检索、论文详情、批量查询、全文检测与下载能力。适合作为 AI Agent 的学术检索基础设施，可与 PubMed MCP 组合形成更完整的生物医学检索链路。

Release Summary (English) OpenAlex MCP Server is a lightweight MCP (Model Context Protocol) server for academic search. It supports paper search, detailed metadata, batch queries, full-text detection, and downloads. It works great as an AI Agent research backend and can be paired with PubMed MCP for biomedical pipelines.

一个轻量化的 OpenAlex MCP 服务器，可与 PubMed MCP 搭配使用，为 AI Agent 提供快速学术文献检索、详细摘要信息和全文下载能力。

功能特性

• 论文搜索: 通过关键词搜索学术文献，支持多种过滤和排序选项
• 论文详情: 获取单篇论文的完整信息，包括摘要、作者、主题等
• 批量查询: 一次性获取多篇论文的信息，提高效率
• 全文下载: 检测并下载开放获取论文的 PDF 全文
• 章节提取: 从 PDF 中提取并识别论文章节（摘要、引言、方法、结果等）
• 智能缓存: 本地缓存论文元数据，减少 API 调用
• 速率限制: 内置速率限制和指数退避重试机制

快速开始

安装

# 克隆仓库
git clone https://github.com/SecretRichGarden/openAlex-mcp.git
cd openAlex-mcp

# 安装依赖
npm install

配置

1. 复制 .env.example 到 .env：

cp .env.example .env

2. 编辑 .env 文件（可选）：

# OpenAlex API 密钥（可选，但推荐获取以获得更高的速率限制）
# 在 https://openalex.org/register 免费获取
OPENALEX_API_KEY=your-api-key-here

# 启用缓存（默认：true）
CACHE_ENABLED=true

# 摘要处理模式（默认：quick）
ABSTRACT_MODE=quick

运行（本地）

npm start

运行（npx 一键）

npx -y openalex-mcp-server

One-Command Run (npx)

npx -y openalex-mcp-server

魔搭社区 / Smithery 发布用配置（STDIO）

将以下内容复制到 MCP 客户端配置中即可（包含必填 API Key，适合发布页面展示）：

{
  "mcpServers": {
    "openalex-mcp-server": {
      "args": [
        "openalex-mcp-server"
      ],
      "command": "npx",
      "env": {
        "OPENALEX_API_KEY": "your-api-key-here"
      }
    }
  }
}

ModelScope / Smithery STDIO Config (English)

Copy this config into your MCP client configuration (API key required):

{
  "mcpServers": {
    "openalex-mcp-server": {
      "args": [
        "openalex-mcp-server"
      ],
      "command": "npx",
      "env": {
        "OPENALEX_API_KEY": "your-api-key-here"
      }
    }
  }
}

配置 Claude Desktop

将以下配置添加到 Claude Desktop 的配置文件中：

macOS/Linux: ~/.claude/desktop_config.json Windows: %APPDATA%\Claude\desktop_config.json

{
  "mcpServers": {
    "openalex-mcp-server": {
      "command": "node",
      "args": [
        "/path/to/openAlex-mcp/src/cli.js"
      ],
      "env": {
        "OPENALEX_API_KEY": "your-api-key-here",
        "CACHE_ENABLED": "true"
      }
    }
  }
}

或者使用 npx（无需安装）：

{
  "mcpServers": {
    "openalex-mcp-server": {
      "command": "npx",
      "args": ["-y", "openalex-mcp-server"],
      "env": {
        "OPENALEX_API_KEY": "your-api-key-here"
      }
    }
  }
}

配置 Cherry / 其他 MCP 客户端

以下为通用 stdio 配置，适用于 Cherry Studio 或其它支持 MCP 的 Agent 工具。将 command / args 按客户端要求填写即可。

{
  "mcpServers": {
    "openalex-mcp-server": {
      "command": "npx",
      "args": ["-y", "openalex-mcp-server"],
      "env": {
        "OPENALEX_API_KEY": "your-api-key-here",
        "CACHE_ENABLED": "true"
      }
    }
  }
}

Cherry / Other MCP Clients (English)

Use the following stdio configuration for Cherry Studio or any MCP-capable client. Copy and adjust command / args based on your client’s config format.

{
  "mcpServers": {
    "openalex-mcp-server": {
      "command": "npx",
      "args": ["-y", "openalex-mcp-server"],
      "env": {
        "OPENALEX_API_KEY": "your-api-key-here",
        "CACHE_ENABLED": "true"
      }
    }
  }
}

可用工具

openalex_search

搜索学术文献。

参数:

• query (必需): 搜索关键词
• max_results (可选): 每页结果数，默认 20，最大 200
• page (可选): 页码，默认 1
• sort_by (可选): 排序字段，如 "cited_by_count:desc"
• filters (可选): 过滤器对象
  • publication_year: 发表年份
  • is_oa: 是否为开放获取
  • type: 文献类型

返回格式:

{
  "meta": {
    "total_count": 1000,
    "page": 1,
    "per_page": 20
  },
  "papers": [
    {
      "id": "W3128609807",
      "title": "论文标题",
      "authors": [...],
      "publication_year": 2023,
      "venue": {...},
      "cited_by_count": 42,
      "open_access": {...}
    }
  ]
}

openalex_get_work

获取单篇论文的详细信息。

参数:

• work_id (必需): 论文 ID（OpenAlex ID、DOI 或 PMID）
• include_abstract (可选): 是否包含摘要，默认 true
• abstract_mode (可选): 摘要模式（quick/deep），默认 quick

示例:

{
  "work_id": "W3128609807"
}

openalex_batch_get_works

批量获取多篇论文信息。

参数:

• work_ids (必需): 论文 ID 数组（最多 50 个）
• include_abstract (可选): 是否包含摘要，默认 false

示例:

{
  "work_ids": ["W3128609807", "W2741809807", "W2105678901"]
}

openalex_detect_fulltext

检测论文是否有可用的全文。

参数:

• work_id (必需): 论文 ID

返回:

{
  "work_id": "W3128609807",
  "is_oa": true,
  "oa_status": "gold",
  "oa_url": "https://arxiv.org/pdf/2301.xxxxx.pdf",
  "fulltext_available": true
}

openalex_download_fulltext

下载论文全文 PDF。

参数:

• work_id (必需): 论文 ID
• force_download (可选): 强制重新下载，默认 false

返回:

{
  "work_id": "W3128609807",
  "status": "downloaded",
  "cache_path": "/path/to/cache/W3128609807.pdf",
  "file_size": 1234567
}

openalex_get_fulltext_sections

获取论文的章节内容。

参数:

• work_id (必需): 论文 ID
• sections (可选): 要获取的章节列表

可用章节:

• abstract
• introduction
• methods
• results
• discussion
• conclusion
• references

openalex_cache_stats

查看缓存统计信息。

参数:

• action (可选): "stats" 或 "clear"，默认 stats

openalex_system_check

检查系统状态和 API 连接。

参数: 无

使用示例

示例 1: 搜索机器学习相关的高被引论文

{
  "tool": "openalex_search",
  "arguments": {
    "query": "machine learning",
    "max_results": 10,
    "sort_by": "cited_by_count:desc",
    "filters": {
      "publication_year": 2023,
      "is_oa": true
    }
  }
}

示例 2: 获取论文详情并下载全文

{
  "tool": "openalex_get_work",
  "arguments": {
    "work_id": "W3128609807",
    "include_abstract": true
  }
}

{
  "tool": "openalex_download_fulltext",
  "arguments": {
    "work_id": "W3128609807"
  }
}

{
  "tool": "openalex_get_fulltext_sections",
  "arguments": {
    "work_id": "W3128609807",
    "sections": ["abstract", "introduction", "methods"]
  }
}

示例 3: 批量获取论文信息

{
  "tool": "openalex_batch_get_works",
  "arguments": {
    "work_ids": [
      "W3128609807",
      "W2741809807",
      "W2105678901"
    ]
  }
}

示例 4: 与 PubMed MCP 配合使用

配置两个 MCP 服务器可以同时使用：

{
  "mcpServers": {
    "openalex-mcp-server": {
      "command": "node",
      "args": ["/path/to/openAlex-mcp/src/cli.js"],
      "env": {
        "OPENALEX_API_KEY": "your-key"
      }
    },
    "pubmed-mcp-server": {
      "command": "npx",
      "args": ["-y", "@your-org/pubmed-mcp"]
    }
  }
}

工作流程：

1. 使用 OpenAlex 搜索论文获取广泛的学术文献
2. 使用 PubMed 获取生物医学领域的详细元数据
3. 使用 OpenAlex 下载全文并提取章节

配置选项

环境变量

| 变量 | 类型 | 默认值 | 描述 | |------|------|--------|------| | OPENALEX_API_KEY | string | - | OpenAlex API 密钥（可选） | | CACHE_ENABLED | boolean | true | 是否启用本地缓存 | | ABSTRACT_MODE | string | quick | 摘要处理模式 |

Environment Variables (English)

| Variable | Type | Default | Description | |------|------|--------|------| | OPENALEX_API_KEY | string | - | OpenAlex API key (optional) | | CACHE_ENABLED | boolean | true | Enable local cache | | ABSTRACT_MODE | string | quick | Abstract processing mode |

API 密钥

虽然不需要 API 密钥也可以使用 OpenAlex API，但注册并使用 API 密钥可以获得：

• 更高的速率限制（有密钥：10 请求/秒，无密钥：5 请求/秒）
• 更稳定的服务体验

在 https://openalex.org/register 免费获取 API 密钥。

API Key (English)

You can use OpenAlex without a key, but a key increases rate limits and stability. Get a free API key at https://openalex.org/register.

项目结构

openalex-mcp/
├── src/
│   ├── index.js                 # MCP 服务器入口
│   ├── openalex-client.js       # OpenAlex API 客户端
│   ├── cache-manager.js         # 缓存管理器
│   ├── fulltext-downloader.js   # 全文下载器
│   ├── json-optimizer.js        # JSON 格式优化器
│   └── utils.js                 # 工具函数
├── config/
│   └── mcp-config.json          # MCP 配置模板
├── cache/
│   ├── papers/                  # 论文元数据缓存
│   └── fulltext/                # 全文 PDF 和文本缓存
├── package.json
├── .env.example
└── README.md

开发

类型检查

npm run typecheck

运行测试

npm test

常见问题

Q: 为什么搜索结果为空？

A: 可能的原因：

1. 搜索关键词太具体或拼写错误
2. 应用了过于严格的过滤条件
3. 网络连接问题

Q: 全文下载失败怎么办？

A: 检查以下几点：

1. 论文是否为开放获取（OA）
2. OA URL 是否有效
3. 网络连接是否正常
4. 使用 openalex_detect_fulltext 工具检查可用性

Q: 如何提高 API 请求速率？

A: 注册并配置 OpenAlex API 密钥可以将速率从 5 请求/秒提高到 10 请求/秒。

Q: 缓存占用空间太大怎么办？

A: 使用 openalex_cache_stats 工具查看缓存大小，并定期清理 cache/ 目录。

许可证

ISC

贡献

欢迎提交 Issue 和 Pull Request！

相关链接

• OpenAlex API 文档
• MCP 协议规范
• Claude Desktop 配置指南

Made with ❤️ for the AI research community