Skip to main content
Glama
SecretRichGarden

OpenAlex MCP Server

by SecretRichGarden
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

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 调用

  • 速率限制: 内置速率限制和指数退避重试机制

Related MCP server: scholar-toolkit-mcp

快速开始

安装

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

# 安装依赖
npm install

配置

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

cp .env.example .env

  1. 编辑 .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！

相关链接

Made with ❤️ for the AI research community

Available Tools

8 tools
openalex_batch_get_worksA

Get information for multiple papers in one request. More efficient than calling get_work multiple times.

ParametersJSON Schema
NameRequiredDescriptionDefault
work_idsYesArray of paper IDs (OpenAlex IDs only, max 50)
include_abstractNoInclude abstracts in response (default: false for performance)

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It mentions the max 50 IDs in the schema but does not disclose behavioral traits like id validation, error handling, or performance impact. This is adequate but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences, no wasted words. It front-loads the main purpose and efficiently indicates efficiency benefit.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (batch get) and absence of output schema, the description is mostly complete. It covers purpose and efficiency. However, it does not mention return format or error behavior, which would be helpful for completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, as both parameters are described in the input schema. The description does not add new information beyond what the schema already provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (Get information) and the resource (multiple papers) with a specific verb and resource. It also distinguishes from the sibling tool 'get_work' by implying batch vs single, fulfilling the criterion for specific verb+resource and sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description identifies when to use this tool ('for multiple papers') and contrasts with an alternative ('more efficient than calling get_work multiple times'). It does not explicitly state when not to use it or context exclusions, but it provides clear usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openalex_cache_statsC

Get cache statistics or clear the cache. Shows number of cached papers, total size, and cache directory.

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNoAction: "stats" for statistics or "clear" to clear cachestats

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It discloses that 'stats' shows cached papers count, size, and directory, but does not warn that 'clear' is destructive (data loss) or discuss permissions. Behavior for 'clear' is opaque.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste. Front-loads the primary purpose and then details output. Could be slightly more structured, but overall efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple cache tool: describes both actions and output for stats. Lacks details on return format (e.g., JSON) and effect of clear. No output schema; description could be more complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%. The description adds minimal value beyond the schema: it links the action parameter to the two operations. Baseline 3 is appropriate as the schema already defines the enum and default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool shows cache statistics or clears the cache, using specific verbs ('Get', 'clear') and resource ('cache statistics'). However, it does not explicitly differentiate from sibling tools, though the unique function is evident.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, nor on whether to use 'stats' or 'clear'. The description lacks context about appropriate use cases or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openalex_detect_fulltextA

Check if full text is available for a paper and get the open access URL if available.

ParametersJSON Schema
NameRequiredDescriptionDefault
work_idYesPaper identifier (OpenAlex ID, DOI, or PMID)

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must disclose all behaviors. It states the action but does not mention side effects, errors, or output format. Adequate but minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words, directly states purpose. Front-loaded with key action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given simplicity (1 param, no output schema), description is mostly complete. However, it could mention that it returns a URL or null for clarity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema already provides full coverage for the single parameter (work_id). Description adds no extra meaning beyond what schema defines.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it checks full-text availability and gets open access URL. Distinct from siblings like openalex_download_fulltext and openalex_get_fulltext_sections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance. Usage is implied but not directly stated relative to siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openalex_download_fulltextA

Download full text PDF for an open access paper. Returns the cached file path on success.

ParametersJSON Schema
NameRequiredDescriptionDefault
work_idYesPaper identifier (OpenAlex ID, DOI, or PMID)
force_downloadNoForce re-download even if cached (default: false)

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavior. It mentions caching and returns the file path, but does not cover error cases (e.g., non-open access), authentication requirements, or rate limits. It is adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one clear sentence with no redundant information. It front-loads the core action and return value, making it efficient for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 parameters, no output schema, and no annotations, the description covers the main purpose and result. It lacks details on error handling or prerequisites, but is nearly complete for a straightforward download tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the schema already explains the parameters. The description adds no new semantic meaning beyond what is in the schema, resulting in a baseline score of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool downloads full text PDF for open access papers and returns the cached file path. It uses a specific verb and resource, and is distinct from sibling tools like detect_fulltext or get_fulltext_sections.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, such as checking if the paper is open access first via openalex_detect_fulltext. No prerequisites or when-not-to-use conditions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openalex_get_fulltext_sectionsA

Get extracted sections (abstract, introduction, methods, results, discussion, etc.) from a downloaded paper. Will trigger download if not cached.

ParametersJSON Schema
NameRequiredDescriptionDefault
work_idYesPaper identifier (OpenAlex ID, DOI, or PMID)
sectionsNoSpecific sections to retrieve (default: all available sections)

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that tool 'will trigger download if not cached', a key behavioral trait beyond what annotations provide (none given). No annotation contradiction. Could add more about side effects like network latency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the main purpose, no superfluous words. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose and side effect but omits return format, handling of missing sections, and caching details. With no output schema, more detail on output would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters with descriptions. Description adds default behavior for sections (all available) and expands on accepted identifiers (OpenAlex ID, DOI, PMID), providing value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Get extracted sections from a downloaded paper' with a specific verb and resource. It also notes a side effect (trigger download if not cached), distinguishing it from sibling tools like openalex_download_fulltext and openalex_get_work.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings, nor any when-not-to-use conditions. The description does not mention prerequisites or context for triggering downloads.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openalex_get_workA

Get detailed information about a specific paper by its OpenAlex ID, DOI, or PMID. Includes full abstract, author information, topics, and references count.

ParametersJSON Schema
NameRequiredDescriptionDefault
work_idYesPaper identifier (OpenAlex ID like W1234567890, DOI like 10.xxx, or PMID)
include_abstractNoInclude abstract in response (default: true)
abstract_modeNoAbstract processing mode: "quick" (cached) or "deep" (fetch new)

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so description carries full burden. It lists returned fields but does not disclose behavioral traits like caching, abstract mode differences (quick vs deep), or any side effects. Basic coverage but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with action and resource, no redundant words. Efficient and clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description helps by listing included fields (abstract, author, topics, references count). However, it omits explanation of abstract modes and response format details. Nearly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline 3. The description adds context about returned content but does not enhance parameter meaning beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'get' and resource 'paper', specifies three identifier types (OpenAlex ID, DOI, PMID), and differentiates from sibling batch tool by focusing on a single work.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied for single paper retrieval, but no explicit when-to-use or alternatives guidance is given. The sibling tool openalex_batch_get_works suggests batch use, but the description does not clarify when to choose this tool over the batch one.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

openalex_system_checkA

Check system status and API connectivity. Returns health status, API reachability, cache status, and version info.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description adequately discloses the tool's behavior: it returns health status, API reachability, cache status, and version info. It is non-destructive and read-only, but this is not explicitly stated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the purpose and listing return values efficiently. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter health check tool, the description covers key return values. It could hint at intended frequency (e.g., 'call before other operations') but is otherwise sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the baseline is 4. The description correctly indicates no input is required, and the schema coverage is 100%.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks system status and API connectivity, using specific terms like health status, API reachability, cache status, and version info. It distinguishes itself from sibling tools which focus on works and fulltext operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly suggests using this tool to verify system health or API connectivity before other operations, but does not explicitly state when not to use it or mention alternative tools for similar checks.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv1.0.6
    • First observedopenalex_batch_get_works
    • First observedopenalex_cache_stats
    • First observedopenalex_detect_fulltext
    • First observedopenalex_download_fulltext
    • First observedopenalex_get_fulltext_sections
    • First observedopenalex_get_work
    • First observedopenalex_search
    • First observedopenalex_system_check
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.8/5.0

Scored across 8 tools

Disambiguation5/5

Each tool has a distinct purpose: searching, retrieving works, batch queries, fulltext handling, cache management, and system checks. No overlap or ambiguity.

Naming Consistency5/5

All tools follow the consistent pattern 'openalex_' + verb_phrase in snake_case, making them predictable and easy to understand.

Tool Count5/5

With 8 tools, the server is well-scoped for its purpose of querying and downloading academic papers. Each tool earns its place without being overwhelming.

Completeness4/5

The tool surface covers search, retrieval, batch operations, fulltext detection/download, section extraction, cache stats, and system status. Minor gaps: no direct author/institution endpoints, but works include that data.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • academic-mcp

    dopawei
    A
    license
    A
    quality
    D
    maintenance
    Unified academic search MCP server that searches open literature (arXiv, bioRxiv, medRxiv, PMC), CNKI, and Web of Science, with browser-backed authentication, local paper library, and export to multiple formats.
    21
    2
    MIT

  • scholar-toolkit-mcp

    czwziy
    A
    license
    A
    quality
    A
    maintenance
    Comprehensive MCP server for academic research workflows, enabling paper searching across multiple sources, manuscript processing with citation placeholders, search caching, and citation export.
    11
    MIT

  • aigroup-paper-mcp

    jackdark425
    A
    license
    A
    quality
    D
    maintenance
    Academic paper search and retrieval MCP server integrating multiple scholarly platforms into a unified interface. Supports search, fetch, trend analysis, and literature review workflows.
    8
    42 npm
    3
    MIT

  • pubmed-clinical-mcp

    jxia622
    A
    license
    A
    quality
    C
    maintenance
    A lightweight MCP server for clinical biomedical literature retrieval, enabling PubMed search, article metadata, full-text access, and evidence summarization through MCP-compatible clients.
    10
    MIT